Padrões de Servidor MCP

O Model Context Protocol (MCP) permite que assistentes de IA chamem ferramentas, leiam recursos e usem prompts do seu servidor. Use esta habilidade ao construir ou manter servidores MCP. A API do SDK evolui; consulte o Context7 (documentos de consulta para "MCP") ou a documentação oficial do MCP para nomes e assinaturas de métodos atuais.

Para a decisão de roteamento mais ampla sobre quando uma capacidade deve ser uma regra, uma habilidade, MCP ou um fluxo de trabalho simples de CLI/API, consulte docs/capability-surface-selection.md.

Quando Usar

Use quando: implementar um novo servidor MCP, adicionar ferramentas ou recursos, escolher stdio vs HTTP, atualizar o SDK ou depurar problemas de registro e transporte do MCP.

Como Funciona

Conceitos Principais

• Ferramentas: Ações que o modelo pode invocar (por exemplo, pesquisar, executar um comando). Registre com registerTool() ou tool() dependendo da versão do SDK.
• Recursos: Dados somente leitura que o modelo pode buscar (por exemplo, conteúdo de arquivos, respostas de API). Registre com registerResource() ou resource(). Os manipuladores geralmente recebem um argumento uri.
• Prompts: Modelos de prompt reutilizáveis e parametrizados que o cliente pode expor (por exemplo, no Claude Desktop). Registre com registerPrompt() ou equivalente.
• Transporte: stdio para clientes locais (por exemplo, Claude Desktop); HTTP Streamable é preferível para remotos (Cursor, nuvem). HTTP/SSE legado é para compatibilidade com versões anteriores.

O SDK Node/TypeScript pode expor tool() / resource() ou registerTool() / registerResource(); o SDK oficial mudou ao longo do tempo. Sempre verifique em relação aos documentos do MCP atuais ou ao Context7.

Conectando com stdio

Para clientes locais, crie um transporte stdio e passe-o para o método connect do seu servidor. A API exata varia de acordo com a versão do SDK (por exemplo, construtor vs. fábrica). Consulte a documentação oficial do MCP ou consulte o Context7 para "servidor MCP stdio" para o padrão atual.

Mantenha a lógica do servidor (ferramentas + recursos) independente do transporte para que você possa conectar stdio ou HTTP no ponto de entrada.

Remoto (HTTP Streamable)

Para Cursor, nuvem ou outros clientes remotos, use HTTP Streamable (um único endpoint HTTP MCP por especificação atual). Suporte HTTP/SSE legado apenas quando a compatibilidade com versões anteriores for necessária.

Exemplos

Instalação e configuração do servidor

npm install @modelcontextprotocol/sdk zod

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

Registre ferramentas e recursos usando a API que sua versão do SDK fornece: algumas versões usam server.tool(name, description, schema, handler) (argumentos posicionais), outras usam server.tool({ name, description, inputSchema }, handler) ou registerTool(). O mesmo para recursos — inclua um uri no manipulador quando a API o fornecer. Verifique os documentos oficiais do MCP ou o Context7 para as assinaturas @modelcontextprotocol/sdk atuais para evitar erros de copiar e colar.

Use Zod (ou o formato de esquema preferido do SDK) para validação de entrada.

Melhores Práticas

• Schema primeiro: Defina esquemas de entrada para cada ferramenta; documente parâmetros e a forma de retorno.
• Erros: Retorne erros estruturados ou mensagens que o modelo possa interpretar; evite rastreamentos de pilha brutos.
• Idempotência: Prefira ferramentas idempotentes sempre que possível para que as retentativas sejam seguras.
• Taxa e custo: Para ferramentas que chamam APIs externas, considere limites de taxa e custos; documente na descrição da ferramenta.
• Versionamento: Fixe a versão do SDK em package.json; verifique as notas de lançamento ao atualizar.

SDKs e Documentos Oficiais

• JavaScript/TypeScript: @modelcontextprotocol/sdk (npm). Use o Context7 com o nome da biblioteca "MCP" para padrões atuais de registro e transporte.
• Go: SDK oficial Go no GitHub (modelcontextprotocol/go-sdk).
• C#: SDK oficial C# para .NET.