MCP Simple Server

Um servidor MCP simples com transporte HTTP streamable que suporta ferramentas matemáticas básicas como adição e multiplicação.

GitHub
1
Experimente este MCPPatrocinado

Documentação

MCP Simple Server

Uma implementação mínima e de referência de um servidor Model Context Protocol com transporte HTTP streamable. Construído com FastMCP seguindo a especificação oficial do MCP da Anthropic 2025-06-18. Ponto de partida perfeito para criar servidores MCP remotos.

🎯 Objetivo

Este projeto serve como uma referência simples e bem documentada para desenvolvedores que desejam:

  • Criar seu primeiro servidor MCP
  • Implantar servidores MCP em plataformas de nuvem (Railway, Heroku, Render)
  • Entender a implementação do protocolo MCP
  • Criar uma base para soluções MCP mais sofisticadas

Recursos

  • ✅ Duas Ferramentas Matemáticas: funções add e multiply
  • ✅ Transporte HTTP Streamable: Protocolo MCP moderno com suporte a SSE
  • ✅ Gerenciamento de Sessão: Fluxo de inicialização MCP adequado
  • ✅ Implantação Remota: Configurações de implantação para Railway, Heroku, Render
  • ✅ Testes Automatizados: Ferramentas completas de validação e depuração de protocolo
  • ✅ Integração com Claude Desktop: Pronto para integração com assistentes de IA
  • ✅ Implementação de Referência: Código bem documentado para aprendizado

Início Rápido

Desenvolvimento Local

git clone https://github.com/oleksandrsirenko/mcp-simple-server.git
cd mcp-simple-server
uv sync
source .venv/bin/activate
python main.py

O servidor inicia em: http://localhost:8000/mcp/

Testar o Servidor

python test_server.py

Saída esperada:

🧪 Starting MCP Server Tests
✅ Initialize successful - Server: Simple Server
✅ Initialized notification sent
✅ Found 2 tools: add, multiply  
✅ Add tool returned correct result
✅ Multiply tool returned correct result
🎉 All tests passed!

Ferramentas Disponíveis

add(a, b)

Soma dois números.

Exemplo:

{"name": "add", "arguments": {"a": 25, "b": 17}}
→ Returns: 42

multiply(a, b)

Multiplica dois números.

Exemplo:

{"name": "multiply", "arguments": {"a": 8, "b": 6}}
→ Returns: 48

Teste Manual com curl

Teste Local (Desenvolvimento)

Para testar seu servidor de desenvolvimento local rodando em localhost:8000:

1. Inicializar Sessão

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"clientInfo":{"name":"test-client","version":"1.0.0"}}}'

2. Enviar Notificação de Inicialização

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

3. Listar Ferramentas

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

4. Chamar Ferramenta de Soma

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add","arguments":{"a":25,"b":17}}}'

Teste Remoto (Produção)

Para testar seu servidor implantado, substitua localhost:8000 pela URL da sua implantação:

# Example with Railway deployment
curl -X POST https://your-app.railway.app/mcp/ \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"clientInfo":{"name":"test-client","version":"1.0.0"}}}'

Nota: Para testes remotos abrangentes, use o script de teste automatizado:

python test_deployment.py your-app.railway.app

Implantação

Railway (Recomendado)

  1. Envie para o GitHub:

    git add .
git commit -m "ready for deployment"
git push origin main

  2. Implante no Railway:

    • Acesse railway.app
    • Clique em "Deploy from GitHub repo"
    • Selecione seu repositório
    • O Railway detecta automaticamente o Dockerfile e implanta

  3. Teste sua implantação:

    python test_deployment.py your-app-name.up.railway.app

  4. Sua URL MCP: https://your-app.railway.app/mcp/

Heroku

heroku create your-mcp-server
git push heroku main

Sua URL MCP: https://your-mcp-server.herokuapp.com/mcp/

Render

  1. Conecte o repositório GitHub ao Render
  2. O Render detecta automaticamente render.yaml e o Dockerfile
  3. Implanta automaticamente

Sua URL MCP: https://your-service.onrender.com/mcp/

Docker

docker build -t mcp-simple-server .
docker run -p 8000:8000 mcp-simple-server

Integração com Claude Desktop

Configuração do Servidor Local

{
  "mcpServers": {
    "simple-server": {
      "command": "python",
      "args": ["main.py"],
      "cwd": "/path/to/mcp-simple-server"
    }
  }
}

Configuração do Servidor Remoto (Recomendado)

Para servidores remotos implantados no Railway, Heroku ou Render, use o pacote mcp-remote:

{
  "mcpServers": {
    "simple-server-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-app.railway.app/mcp/",
        "--allow-http",
        "--header",
        "Accept: application/json, text/event-stream"
      ]
    }
  }
}

Notas Importantes de Configuração:

  • Use npx com a flag -y para instalar automaticamente o mcp-remote
  • Inclua a barra final na URL: /mcp/
  • Adicione a flag --allow-http para conexões HTTP
  • Inclua o cabeçalho Accept para suporte adequado a SSE

Alternativa: Proxy Python Direto (Avançado)

Para usuários avançados ou fins de depuração, você pode criar um proxy Python personalizado:

{
  "mcpServers": {
    "simple-server-proxy": {
      "command": "python",
      "args": ["claude_mcp_proxy.py"],
      "cwd": "/path/to/mcp-simple-server"
    }
  }
}

Nota: Isso requer o script claude_mcp_proxy.py do repositório e é principalmente para fins de depuração. Use mcp-remote para produção.

Locais dos Arquivos de Configuração:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Testar com Claude

Após a integração, pergunte ao Claude:

  • "Você pode somar 42 e 18 para mim?"
  • "Quanto é 7 vezes 9?"
  • "Quais ferramentas você tem disponíveis?"

O Claude usará seu servidor MCP para realizar cálculos! 🎉

Desenvolvimento

Adicionando Novas Ferramentas

@mcp.tool()
def subtract(a: float, b: float) -> float:
    """Subtract two numbers"""
    return a - b

@mcp.tool()
def divide(a: float, b: float) -> float:
    """Divide two numbers"""
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b

Variáveis de Ambiente

  • HOST: Host do servidor (padrão: 127.0.0.1, use 0.0.0.0 para implantação)
  • PORT: Porta do servidor (padrão: 8000, o Railway define isso automaticamente)
HOST=0.0.0.0 PORT=3000 python main.py

Nota: Para implantação no Railway, o FastMCP vinculará automaticamente a 0.0.0.0:$PORT.

Estrutura do Projeto

mcp-simple-server/
├── main.py                    # MCP server (~25 lines)
├── test_server.py             # Local server tests (~300 lines)
├── test_deployment.py         # Remote deployment tests
├── test_host_binding.py       # Host binding tests
├── test_proxy_script.py       # Proxy testing script
├── test_streamable_app.py     # Streamable HTTP tests
├── test_tool_verification.py  # Tool verification tests
├── debug_railway_server.py    # Railway debugging utilities
├── debug_fastmcp.py           # FastMCP debugging utilities
├── claude_mcp_proxy.py        # Claude Desktop proxy (optional)
├── start.sh                   # Shell startup script
├── pyproject.toml             # Project configuration
├── README.md                  # This documentation
├── uv.lock                    # Dependency lock file
├── .gitignore                 # Git ignore patterns
├── .python-version            # Python version specification
├── Dockerfile                 # Docker deployment
├── railway.toml               # Railway configuration
├── Procfile                   # Heroku configuration
└── render.yaml                # Render configuration

Arquitetura

  • FastMCP: Implementação MCP de alto nível da Anthropic
  • HTTP Streamable: Transporte moderno com suporte a streaming SSE
  • Gerenciamento de Sessão: Conexões com estado e IDs de sessão
  • JSON-RPC 2.0: Protocolo padrão para troca de mensagens
  • Protocolo 2025-06-18: Especificação MCP mais recente
  • Porta 8000: Porta padrão do servidor FastMCP (configurável via variável de ambiente PORT)

Detalhes Técnicos

Implementação do Servidor

  • Framework: FastMCP (biblioteca oficial da Anthropic)
  • Transporte: HTTP Streamable com Server-Sent Events
  • Protocolo: Especificação MCP 2025-06-18
  • Dependências: httpx>=0.28.1, mcp>=1.9.4

Fluxo do Protocolo MCP

  1. O cliente envia a solicitação initialize
  2. O servidor responde com capacidades e ID de sessão
  3. O cliente envia a notificação initialized
  4. As operações normais começam (tools/list, tools/call, etc.)

Formato de Resposta das Ferramentas

As ferramentas retornam valores Python simples (float, int, str) que o FastMCP encapsula automaticamente no formato de resposta MCP adequado.

Solução de Problemas

O Servidor Não Inicia

# Check if port is in use
lsof -i :8000

# Try different port
PORT=3000 python main.py

Erros de Protocolo MCP

# Run automated test
python test_server.py

# Check server logs for detailed errors

Claude Desktop Não Conecta

  1. Verifique a sintaxe da configuração JSON - Use um validador JSON
  2. Verifique a acessibilidade da URL do servidor - Teste com curl ou navegador
  3. Reinicie o Claude Desktop após alterações na configuração
  4. Garanta o caminho correto do endpoint MCP - Use /mcp/ com barra final
  5. Use mcp-remote para servidores remotos - Não use curl para conexões remotas

Testar Implantação Remota

Teste seu servidor implantado com o script fornecido:

# Test your deployed server (replace with your URL)
python test_deployment.py your-app.railway.app

# Or with full URL
python test_deployment.py https://your-app.railway.app

Isso executará a suíte completa de testes do protocolo MCP contra seu servidor remoto.

Problemas Comuns

  • Endpoint errado: Use /mcp/ (com barra final)
  • Cabeçalhos ausentes: Inclua todos os cabeçalhos MCP necessários
  • Gerenciamento de sessão: Deve enviar a notificação initialized após initialize
  • Conexões remotas: Use mcp-remote, não curl para Claude Desktop
  • Vínculo de porta: Use 0.0.0.0:$PORT para implantação, não 127.0.0.1

Dependências

dependencies = [
    "httpx>=0.28.1",   # HTTP client for testing
    "mcp>=1.9.4",      # Official Anthropic MCP library
]

O projeto usa:

  • mcp: SDK Python oficial do MCP da Anthropic
  • httpx: Cliente HTTP moderno para testes automatizados
  • Python: Requer Python >=3.10

Contribuindo

  1. Faça um fork do repositório
  2. Faça suas alterações
  3. Execute os testes: python test_server.py
  4. Teste a implantação: python test_deployment.py your-test-url
  5. Garanta que todos os testes passem
  6. Envie um pull request

Licença

Licença MIT

Recursos