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 (consulte a documentação com "MCP") ou a documentação oficial do MCP para nomes de métodos e assinaturas atuais.

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

Quando Usar

Use quando: 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 principais

• Ferramentas (Tools): Ações que o modelo pode invocar (ex.: pesquisar, executar um comando). Registre com registerTool() ou tool() dependendo da versão do SDK.
• Recursos (Resources): Dados somente leitura que o modelo pode buscar (ex.: 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 exibir (ex.: no Claude Desktop). Registre com registerPrompt() ou equivalente.
• Transporte: stdio para clientes locais (ex.: Claude Desktop); Streamable HTTP é preferido para remoto (Cursor, nuvem). Legacy HTTP/SSE é 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 connect do seu servidor. A API exata varia de acordo com a versão do SDK (ex.: construtor vs factory). Consulte a documentação oficial do MCP ou consulte o Context7 por "MCP stdio server" 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 (Streamable HTTP)

Para Cursor, nuvem ou outros clientes remotos, use Streamable HTTP (um único endpoint HTTP MCP conforme a 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 manipulador quando a API a fornecer. Consulte a documentação oficial do MCP ou o Context7 para as assinaturas atuais de @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 rastreamentos de pilha 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ções 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 Go oficial no GitHub (modelcontextprotocol/go-sdk).
• C#: SDK C# oficial para .NET.