Creating Your First MCP Server

Learn how to create your first Model Context Protocol server in MA²D with a practical, hands-on tutorial.

What You’ll Build

In this guide, you’ll create a simple weather information MCP server with:

• 1 Tool - get_weather to fetch weather data
• 1 Resource - Weather data for major cities
• 1 Mock Scenario - Realistic test responses

Time Required: 10-15 minutes

Prerequisites

• ✅ MA²D account (Sign up here)
• ✅ Logged into MA²D (Login guide)
• ✅ Basic understanding of JSON

Step 1: Navigate to MCP Servers

1. Login to https://ma2d-ai.com
2. Click “MCP Servers” in the left sidebar
3. You’ll see your server list (empty if this is your first server)

Step 2: Create New Server

Click the ”+ Add MCP Design Spec” button.

You’ll see three creation options:

• Import from URL - For existing MCP servers
• Import OpenAPI - Convert REST APIs
• Create Mock - Build from scratch ✅ We’ll use this

Select “Create Mock”

Step 3: Configure Basic Information

Fill in the server details:

Server Name

weather-api

Description

Weather information API providing current conditions and forecasts for cities worldwide

Version

1.0.0

Provider Information (Optional but Recommended)

• Provider Name: Your Organization Name
• Provider URL: https://yourcompany.com

Click “Create Server” when done.

✅ Your server is now created! You’ll be taken to the server detail page.

Step 4: Add a Tool

Tools are functions that AI agents can call. Let’s add a weather tool.

1. Click the “Tools” tab
2. Click ”+ Add Tool” button

Tool Configuration

Name:

get_weather

Description:

Get current weather conditions for a specified city including temperature, humidity, wind speed, and conditions

Input Schema:

This defines what parameters the tool accepts. Enter this JSON:

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "City name (e.g., San Francisco, London, Tokyo)"
    },
    "units": {
      "type": "string",
      "enum": ["celsius", "fahrenheit"],
      "default": "celsius",
      "description": "Temperature units"
    }
  },
  "required": ["city"]
}

Output Schema (Optional):

Define the expected response format:

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string"
    },
    "temperature": {
      "type": "number"
    },
    "units": {
      "type": "string"
    },
    "conditions": {
      "type": "string"
    },
    "humidity": {
      "type": "number"
    },
    "wind_speed": {
      "type": "number"
    }
  }
}

Click “Save Tool”.

Step 5: Add a Mock Scenario

Mock scenarios provide realistic test responses without needing a real weather API.

1. Stay in the “Tools” tab
2. Find your get_weather tool
3. Click “Add Mock Scenario”

Scenario Configuration

Name:

San Francisco Weather

Condition:

Define when this scenario triggers:

{
  "city": "San Francisco"
}

This means: use this response when city equals “San Francisco”.

Response:

The mock data to return:

{
  "city": "San Francisco",
  "temperature": 65,
  "units": "fahrenheit",
  "conditions": "Partly cloudy",
  "humidity": 72,
  "wind_speed": 12
}

Click “Save Scenario”.

Add More Scenarios (Optional)

Add scenarios for other cities:

New York:

// Condition
{"city": "New York"}
 
// Response
{
  "city": "New York",
  "temperature": 75,
  "units": "fahrenheit",
  "conditions": "Sunny",
  "humidity": 65,
  "wind_speed": 8
}

London:

// Condition
{"city": "London"}
 
// Response
{
  "city": "London",
  "temperature": 15,
  "units": "celsius",
  "conditions": "Rainy",
  "humidity": 85,
  "wind_speed": 15
}

Step 6: Add a Resource (Optional)

Resources provide static data that agents can read. Let’s add a list of supported cities.

1. Click the “Resources” tab
2. Click ”+ Add Resource”

Name:

supported_cities

URI:

weather://cities/supported

Description:

List of cities with available weather data

MIME Type:

application/json

Content:

{
  "cities": [
    {"name": "San Francisco", "country": "USA"},
    {"name": "New York", "country": "USA"},
    {"name": "London", "country": "UK"},
    {"name": "Tokyo", "country": "Japan"},
    {"name": "Paris", "country": "France"}
  ]
}

Click “Save Resource”.

Step 7: Get Your MCP Endpoint

Your server now has a live MCP endpoint you can test!

1. Click the “Endpoints” tab
2. You’ll see your endpoint URL:

https://ma2d.vercel.app/api/platform/YOUR_SERVER_ID/mcp

Copy this URL - you’ll use it to test.

Step 8: Test Your Server

Let’s test the server with cURL:

curl -X POST https://ma2d.vercel.app/api/platform/YOUR_SERVER_ID/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather conditions...",
        "inputSchema": { ... }
      }
    ]
  }
}

Test the Tool

Call your weather tool:

curl -X POST https://ma2d.vercel.app/api/platform/YOUR_SERVER_ID/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_weather",
      "arguments": {
        "city": "San Francisco"
      }
    }
  }'

Expected Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"city\":\"San Francisco\",\"temperature\":65,...}"
    }]
  }
}

✅ Success! Your MCP server is working!

Step 9: Check Compliance

MA²D automatically checks your server against design rules.

1. Click the “Compliance” tab
2. Review your compliance score
3. Fix any violations if needed

Common issues for new servers:

• Missing description
• Tool names not snake_case
• No mock scenarios

Step 10: Enable the Server

Your server starts as a draft. Enable it to make it active:

1. Click the “Settings” tab
2. Toggle “Enabled” to ON
3. Server is now active and serving requests!

What You’ve Accomplished

Congratulations! You’ve created your first MCP server with:

• ✅ Server Configuration - Basic info and metadata
• ✅ Tool Definition - get_weather tool with schema
• ✅ Mock Scenarios - Test data for multiple cities
• ✅ Resource - List of supported cities
• ✅ Live Endpoint - Working MCP HTTP endpoint
• ✅ Testing - Verified with cURL

Next Steps

Enhance Your Server

• Add more tools - weather forecasts, historical data
• Add more mock scenarios - cover edge cases
• Add more resources - weather alerts, radar data

Test with AI Clients

Use your MCP server with:

• MCP Inspector: npx @modelcontextprotocol/inspector YOUR_ENDPOINT
• Claude Desktop (configure in settings)
• Custom AI applications

Publish to Exchange

When ready, publish to Anypoint Exchange:

1. Configure Anypoint credentials in Settings
2. Click “Publish to Exchange” on your server
3. Fill in Exchange metadata
4. Publish!

See Publishing to Exchange guide.

Common Issues

Tool Call Returns Empty

Problem: Mock scenario not matching

Solution: Check scenario condition matches exactly. JSON keys and values are case-sensitive.

Compliance Score Low

Problem: Design rule violations

Solution: Go to Compliance tab, read violations, fix issues. Common fixes:

• Use snake_case for names
• Add detailed descriptions
• Create mock scenarios

Endpoint 404

Problem: Server not enabled or incorrect URL

Solution:

• Ensure server is enabled in Settings
• Verify Server ID in URL is correct
• Check server exists in your list

Tips & Best Practices

Tool Design

• Clear Names - Use descriptive, action-oriented names
• Good Descriptions - Explain what, why, and how
• Complete Schemas - Define all parameters clearly
• Example Data - Provide realistic mock scenarios

Resource URIs

Follow conventions:

• weather://cities/list - List endpoints
• weather://cities/{id} - Specific items
• weather://data/current - Current data

Mock Scenarios

• Cover Common Cases - Most frequent inputs
• Edge Cases - Unusual but valid inputs
• Error Cases - Invalid inputs (optional)
• Realistic Data - Use real-world-like values

Learn More

• MCP Protocol - Deep dive into MCP
• MCP Servers Feature - All server features
• Testing MCP Endpoints - Advanced testing
• API Reference - Complete API docs

Congratulations! You’ve built your first MCP server! 🎉

Try building more complex servers or explore other guides to learn more about MA²D.