mcp-server-patterns

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 este skill ao construir ou manter servidores MCP. A API do SDK evolui; verifique o Context7 (query-docs para "MCP") ou a documentação oficial do MCP para nomes e assinaturas de métodos atuais.

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

Quando Usar

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

Como Funciona

Conceitos centrais

• 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 handlers geralmente recebem um argumento uri.
• Prompts: Modelos de prompt reutilizáveis e parametrizados que o cliente pode exibir (por exemplo, no Claude Desktop). Registre com registerPrompt() ou equivalente.
• Transporte: stdio para clientes locais (por exemplo, Claude Desktop); Streamable HTTP é preferido para remoto (Cursor, nuvem). HTTP/SSE legado é para compatibilidade reversa.

O SDK Node/TypeScript pode expor tool() / resource() ou registerTool() / registerResource(); o SDK oficial mudou ao longo do tempo. Sempre verifique a documentação atual do MCP ou o Context7.

Conectando com stdio

Para clientes locais, crie um transporte stdio e passe-o para o método de conexão do seu servidor. A API exata varia conforme a versão do SDK (por exemplo, construtor vs fábrica). Consulte a documentação oficial do MCP ou consulte o Context7 para "MCP stdio server" para obter 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 (Streamable HTTP)

Para Cursor, nuvem ou outros clientes remotos, use Streamable HTTP (um único endpoint HTTP MCP por especificação atual). Suporte HTTP/SSE legado apenas quando a compatibilidade reversa 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 vale para recursos — inclua uma uri no handler quando a API a fornecer. Verifique a documentação oficial do MCP ou o Context7 para as assinaturas atuais do @modelcontextprotocol/sdk 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

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

SDKs e Documentação Oficiais

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