Construa Seu Próprio Servidor MCP do Zero

Todo agente de IA tem o mesmo gargalo: ele só pode raciocinar sobre o que pode alcançar. Os servidores MCP dissolvem essa barreira. Eles expõem ferramentas, recursos e prompts para qualquer cliente compatível através de um formato de wire JSON-RPC tão enxuto que você pode implementá-lo em uma tarde. No entanto, a maioria dos desenvolvedores pega um framework, copia um template e entrega algo que mal conseguem depurar. O Forge começa de maneira diferente. Você construirá um servidor MCP a partir do protocolo básico, entenderá cada byte na comunicação e ganhará o modelo mental que torna cada servidor futuro trivial.

A Ideia (60 Segundos)

O MCP é um protocolo JSON-RPC 2.0. Um cliente envia uma solicitação. Seu servidor retorna uma resposta. Três tipos de solicitação alimentam o loop central:

• initialize, handshake. Cliente e servidor trocam capacidades.

• tools/list, descoberta. O servidor retorna todas as ferramentas que oferece, cada uma com um JSON Schema descrevendo suas entradas.

• tools/call, execução. O cliente nomeia uma ferramenta e passa argumentos. O servidor executa o manipulador e retorna conteúdo estruturado.

O transporte é stdio (JSON-RPC sobre stdin/stdout) ou HTTP (HTTP transmitível). Stdio é o lugar mais simples para começar: leia uma linha do stdin, analise-a, despache, escreva uma linha para stdout.

Essa é toda a arquitetura. Tudo o que vem a seguir é tratamento de erros, validação de esquema e ergonomia.

Por Que Isso Importa

Os servidores MCP são as novas APIs. Onde o REST deu aos sistemas pontos finais, o MCP dá aos agentes ferramentas com entradas tipadas e saídas estruturadas. Cada camada de integração, desde assistentes de IDE até fluxos de trabalho autônomos, converge para este protocolo. O padrão é jovem. Os primitivos são estáveis. A área de superfície é pequena o suficiente para caber na sua cabeça de uma só vez.

Conhecer o formato de comunicação lhe dá três vantagens que os frameworks obscurecem:

• Depuração, quando uma chamada de ferramenta falha, você pode ler a mensagem JSON-RPC bruta e localizar a falha em segundos.

• Portabilidade, qualquer linguagem, qualquer runtime, qualquer transporte. Escreva um servidor em Bash se quiser. O protocolo é o contrato.

• Evolução, o MCP adicionará capacidades. Entender o protocolo base permite que você adote novos recursos por extensão, sempre, evitando reescritas completas.

Os artigos do Forge se baseiam nessa fundação. Se você entender as três solicitações principais e o envelope JSON-RPC, cada padrão subsequente é apenas um novo manipulador.

ArchonHQ é uma publicação apoiada por leitores. Para receber novas postagens e apoiar meu trabalho, considere se tornar um assinante gratuito ou pago.

Passo a Passo

O Envelope JSON-RPC

Cada mensagem compartilha a mesma forma:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "city": "Portland" }
  }
}

A resposta espelha isso:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "72°F, céu limpo" }
    ]
  }
}

Erros trocam result por error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Parâmetros inválidos: faltando 'cidade'"
  }
}

Três campos são importantes: jsonrpc (sempre "2.0"), id (correlaciona solicitação à resposta) e method (a chave de despacho).

Design do Esquema da Ferramenta

Cada ferramenta se anuncia através de um objeto JSON Schema. Um esquema bem projetado é a diferença entre uma ferramenta que os agentes usam e uma que eles tropeçam.

{
  "name": "get_weather",
  "description": "Recuperar o clima atual para uma cidade dada",
  "inputSchema": {
    "type": "object",
    "properties": {