MCP Servers

Understanding Model Context Protocol (MCP) servers and their architecture

What is MCP?

The Model Context Protocol (MCP) is an open standard developed by Anthropic that enables seamless integration between AI applications and external data sources and tools.

MCP provides a standardized way for AI models like Claude to interact with various services, databases, and APIs through a unified interface.

Learn More About MCP

Read Anthropic’s official announcement and deep dive into the Model Context Protocol architecture and use cases.

MCP Architecture

Protocol Overview

MCP defines a client-server architecture where:

• MCP Clients (AI applications like Claude Desktop, IDEs)
• MCP Servers (Services that expose tools, resources, and prompts)
• Transport Layer (stdio, HTTP, or WebSocket)

Core Concepts

MCP servers can expose three main primitives:

Tools

Functions that the AI can invoke to perform actions

Resources

Data sources that the AI can read from

Prompts

Pre-built prompt templates

Communication Flow

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "city": "San Francisco",
      "units": "metric"
    }
  },
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "The current weather in San Francisco is 18°C with clear skies."
      }
    ]
  },
  "id": 1
}

MCP Server Structure

Basic Server Implementation

Python Server
from mcp.server import Server
from mcp.types import Tool, TextContent

# Initialize MCP server

server = Server("weather-server")

@server.list_tools()
async def list_tools():
"""List available tools"""
return [
Tool(
name="get_weather",
description="Get current weather for a city",
inputSchema={
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City name"
},
"units": {
"type": "string",
"enum": ["metric", "imperial"],
"description": "Temperature units"
}
},
"required": ["city"]
}
)
]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
"""Execute tool"""
if name == "get_weather":
city = arguments["city"]
units = arguments.get("units", "metric")

        # Fetch weather data
        weather_data = await fetch_weather(city, units)

        return [
            TextContent(
                type="text",
                text=f"Weather in {city}: {weather_data}"
            )
        ]

# Run server

if **name** == "**main**":
server.run()

MCP Server Components

1. Tools

Tools are functions that AI can call to perform actions:

Tool Definition

{
  "name": "search_database",
  "description": "Search the customer database",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query"
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 10
      },
      "filters": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": ["active", "inactive"]
          },
          "created_after": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "required": ["query"]
  }
}

Tool Response

{
  "content": [
    {
      "type": "text",
      "text": "Found 5 customers matching 'tech startup':\n\n1. Acme Corp (ID: 123)\n2. Tech Solutions Inc (ID: 456)\n..."
    },
    {
      "type": "resource",
      "resource": {
        "uri": "database://customers/123",
        "name": "Acme Corp",
        "mimeType": "application/json"
      }
    }
  ],
  "isError": false
}

Error Handling

{
  "content": [
    {
      "type": "text",
      "text": "Error: Database connection timeout. Please try again later."
    }
  ],
  "isError": true
}

2. Resources

Resources provide access to data:

Resource Types

Static Resources

Fixed data like configuration files

Dynamic Resources

Live data from databases or APIs

File Resources

File system access

Network Resources

External API data

Resource Example

@server.list_resources()
async def list_resources():
    return [
        Resource(
            uri="file:///data/customers.json",
            name="Customer Database",
            mimeType="application/json",
            description="All customer records"
        ),
        Resource(
            uri="api://crm/contacts",
            name="CRM Contacts",
            mimeType="application/json",
            description="Live contact data from CRM"
        )
    ]

@server.read_resource()
async def read_resource(uri: str):
    if uri == "file:///data/customers.json":
        data = await read_file("/data/customers.json")
        return [
            TextContent(
                type="text",
                text=data
            )
        ]
    elif uri == "api://crm/contacts":
        contacts = await fetch_crm_contacts()
        return [
            TextContent(
                type="text",
                text=json.dumps(contacts, indent=2)
            )
        ]

3. Prompts

Reusable prompt templates:

@server.list_prompts()
async def list_prompts():
    return [
        Prompt(
            name="customer_analysis",
            description="Analyze customer behavior and trends",
            arguments=[
                PromptArgument(
                    name="customer_id",
                    description="Customer ID to analyze",
                    required=True
                ),
                PromptArgument(
                    name="time_period",
                    description="Analysis time period (days)",
                    required=False
                )
            ]
        )
    ]

@server.get_prompt()
async def get_prompt(name: str, arguments: dict):
    if name == "customer_analysis":
        customer_id = arguments["customer_id"]
        time_period = arguments.get("time_period", 30)

        # Fetch customer data
        customer_data = await get_customer_data(customer_id, time_period)

        prompt_text = f"""
        Analyze the following customer data for customer #{customer_id}
        over the last {time_period} days:

        {customer_data}

        Please provide:
        1. Key behavioral patterns
        2. Purchase trends
        3. Engagement metrics
        4. Recommendations for retention
        """

        return GetPromptResult(
            description=f"Customer analysis for #{customer_id}",
            messages=[
                PromptMessage(
                    role="user",
                    content=TextContent(
                        type="text",
                        text=prompt_text
                    )
                )
            ]
        )

MCP Server Best Practices

Clear Tool Names - Use descriptive, action-oriented names (e.g., get_weather, search_database)

Comprehensive Schemas - Define all parameters with descriptions and constraints

Error Handling - Return helpful error messages with context

Rate Limiting - Implement rate limits to prevent abuse

Logging - Log all tool invocations for debugging and analytics

Security - Validate inputs, sanitize outputs, use authentication

Documentation - Provide clear descriptions for all tools and resources

Testing - Write comprehensive tests for all functionality

SuperBox MCP Integration

SuperBox provides a complete platform for publishing, discovering, and running MCP servers:

1. Create MCP Server

   Develop your MCP server using any supported language:

   superbox init my-mcp-server --template python
   
2. Test Locally

   Test your server with the SuperBox playground:

   superbox run my-mcp-server
   
3. Security Scan

   Automatic 5-step security pipeline:

   • SonarQube: Code quality
   • Bandit: Python security
   • GitGuardian: Secrets detection
   • Semgrep: Vulnerability scanning
   • OWASP: Dependency check
4. Publish to SuperBox

   Deploy to SuperBox marketplace:

   superbox push
   
5. Sandboxed Execution

   Your MCP server runs in isolated AWS Lambda environments with:

   • Network isolation
   • Resource limits
   • Timeout protection
   • Automatic scaling

Example MCP Servers

Weather MCP

Real-time weather data from multiple APIs Tools: - get_current_weather - get_forecast - get_historical_data

Database MCP

Safe database querying interface Tools: - search_records - get_statistics

• export_data

File System MCP

Secure file operations Tools: - read_file - list_directory - search_files

API Integration MCP

Connect to external services Tools: - call_api - transform_data - cache_results

Protocol Specification

Full MCP specification: modelcontextprotocol.io

JSON-RPC 2.0

MCP uses JSON-RPC 2.0 for communication:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Supported Transports

stdio

Standard input/output for local processes:

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["-m", "weather_mcp"]
    }
  }
}

HTTP/SSE

HTTP with Server-Sent Events:

{
  "mcpServers": {
    "weather": {
      "url": "https://api.weather-mcp.com"
    }
  }
}

WebSocket

Bidirectional WebSocket connection:

{
  "mcpServers": {
    "weather": {
      "url": "wss://api.weather-mcp.com/ws"
    }
  }
}

Next Steps

CLI Guide

Learn to use SuperBox CLI

Sandboxes

Understand Lambda sandboxing

Security

5-step security pipeline

API Reference

Explore SuperBox APIs