Quick Start Guide

Quick Start Guide

Welcome! This guide will help you create your first MCP server in just 5 minutes. By the end, you'll have a working server deployed to MCP.soy's cloud infrastructure that can respond to LLM requests.

Step 1: Create Your Account

First, you'll need a free MCP.soy account:

1. Go to mcp.soy
2. Click "Sign Up" in the top right
3. Enter your email and choose a password
4. Verify your email address

That's it! You're ready to create your first server.

Step 2: Create a New MCP Server

Once logged in:

1. Click "New Server" on your dashboard
2. Fill in the basic information:
   • Name: "My First MCP Server"
   • Description: "A simple server to get started with MCP"
   • Slug: This will auto-generate from your name
3. Click "Create Server"

Congratulations! You've created your first MCP server. Now let's add some functionality.

Step 3: Add Your First Tool

Tools are functions that LLMs can call. Let's create a simple greeting tool:

1. On your server page, click "Add Tool"
2. Fill in the tool details:
   • Title: "Greet User" (This is the human-readable display name)
   • Function Name: greet_user (This is what the LLM will call)
   • Description: "Generates a friendly greeting for a user in different languages"

Define Input Schema

Switch to the Schema tab and use the visual schema editor to define inputs:

Click the Add Field button to add each field:

• First field:
  • Name: person_name
  • Type: String
  • Description: "The name of the person to greet"
  • Required: Yes (check the box)
• Click Add Field again for the second field:
  • Name: language
  • Type: String
  • Description: "The language for the greeting"
  • Default: "english"
  • Add enum values: "english", "spanish", "french"

Implement the Tool

Now switch to the Code tab. You'll see the tool structure is already set up based on your inputs. The code follows this pattern:

// Tool metadata comments
// Tool: greet_user
// Title: Greet User
// Description: Generates a friendly greeting for a user in different languages

import { validateInput, logger } from '../common/utils.js';

// Tool metadata (already filled from your inputs)
export const metadata = {
  name: "greet_user",
  title: "Greet User",
  description: "Generates a friendly greeting for a user in different languages",
  inputSchema: {
    type: "object",
    properties: {
      person_name: {
        type: "string",
        description: "The name of the person to greet"
      },
      language: {
        type: "string",
        description: "The language for the greeting",
        enum: ["english", "spanish", "french"],
        default: "english"
      }
    },
    required: ["person_name"]
  }
};

// Tool implementation - you need to complete this
export async function execute(args, progressToken, server) {
  // Validate input
  const validation = validateInput(args, metadata.inputSchema);
  if (!validation.valid) {
    throw new Error(`Input validation failed: ${validation.errors.join(', ')}`);
  }
  
  logger(`Executing ${metadata.name}`, 'info');
  
  // Your implementation goes here
  const { person_name, language = "english" } = args;
  
  // Define greetings for each language
  const greetings = {
    english: `Hello ${person_name}! Welcome to MCP.`,
    spanish: `¡Hola ${person_name}! Bienvenido a MCP.`,
    french: `Bonjour ${person_name}! Bienvenue sur MCP.`
  };
  
  // Return the appropriate greeting
  return {
    greeting: greetings[language] || greetings.english,
    timestamp: new Date().toISOString(),
    language_used: language
  };
}

Click "Create Tool" to save your tool.

Step 4: Deploy Your Server

Your server needs to be deployed before you can test it:

1. Go back to your server's main page
2. Click "Deploy" in the server actions
3. Wait for deployment to complete (typically 30-60 seconds)

Step 5: Test Your Tool

Once deployed, you can test your tool directly in the interface:

1. Go to your tool's page
2. Click the "Test" tab
3. You'll see input fields generated from your schema:
   • Enter "Alice" for person_name
   • Select "spanish" for language
4. Click "Run Test"
5. You should see the output:

   {
     "greeting": "¡Hola Alice! Bienvenido a MCP.",
     "timestamp": "2025-07-15T12:00:00.000Z",
     "language_used": "spanish"
   }

Step 6: Connect with Claude

Your server is now live! Here's how to use it with Claude:

1. On your server page, find the connection URL (it will look like mcp://your-account/your-server-slug@$LATEST)
2. Go to claude.ai/settings/connectors
3. Click "Connect MCP server"
4. Enter your server's connection URL
5. Click "Connect"
6. Start a new conversation with Claude
7. Try asking: "Can you greet me in French? My name is Claude."

Claude will automatically discover and use your greeting tool!

What You've Learned

In just 5 minutes, you've:

• ✅ Created an MCP server on MCP.soy
• ✅ Built a tool with the visual schema editor
• ✅ Implemented tool logic following MCP patterns
• ✅ Deployed to cloud infrastructure
• ✅ Tested your tool with real inputs
• ✅ Connected with Claude

Understanding the Architecture

Your MCP server runs on MCP.soy's infrastructure:

• Deployment: Your code runs on AWS Lambda
• Tools: Each tool is a JavaScript function with metadata
• Schema: Input/output validation using JSON Schema
• Testing: Built-in testing interface after deployment
• Versioning: Draft ($LATEST) and published versions

Next Steps

Now that you have a working server, here are some ways to expand it:

Add More Tools

Try creating tools that:

• Perform calculations or data processing
• Fetch data from external APIs
• Generate formatted content
• Interact with configuration fields

Add Configuration Fields

Make your server customizable by adding configuration fields:

• API keys for external services
• User preferences
• Base URLs or endpoints

Example: Add an API key field:

// In your server settings, add a configuration field:
// Name: api_key
// Label: "API Key"
// Type: String
// Required: Yes

// Then access it in your tool:
const apiKey = server?.config?.api_key;

Add Resources

Resources provide reference data to LLMs:

• Documentation files
• API references
• Data templates

Tool Code Best Practices

1. Always validate inputs: Use the validateInput utility
2. Use logging: The logger utility helps with debugging
3. Handle errors gracefully: Provide clear error messages
4. Progress updates: Use server.sendProgress for long operations
5. Return structured data: Match your output schema

Explore More Examples

Check out these resources to learn more:

• MCP Tools Documentation - Deep dive into tool creation
• Example Servers - Full examples with source code
• API Reference - Complete API documentation

Getting Help

If you run into issues:

• Check the error messages in the Test tab
• Use the logger utility to debug your code
• Review your tool's input/output schemas
• Ensure your server is deployed before testing

Share Your Creation

Built something cool? Share it with the community!

1. Publish your server to the marketplace
2. Add comprehensive documentation
3. Share on social media with #McpSoy

Welcome to the MCP community! We can't wait to see what you build. 🚀