Existem 10.000 servidores MCP: aqui está o que separa os bons

1. Ferramentas de curadoria; não descarte toda a sua API

O maior erro: registrar cada endpoint de API como uma ferramenta MCP. Botoi tem mais de 150 pontos finais. Se todas fossem ferramentas MCP, o manifesto da ferramenta consumiria mais de 30.000 tokens antes de uma conversa começa. Isso deixa menos espaço para a pergunta real do usuário, aumenta a chance de o modelo escolher o ferramenta errada e retarda cada solicitação porque o modelo precisa ler centenas de ferramentas definições.

Botoi registra 49. Os critérios de seleção: ferramentas que os desenvolvedores utilizam durante as sessões de codificação (DNS pesquisa, decodificação JWT, geração de hash), ferramentas que produzem modelos de saída estruturados podem raciocinar sobre (validação JSON, detecção de PII) e ferramentas que salvam uma troca de contexto (codificação Base64, metadados de URL extração).

// curated-tools.ts - 49 tools from 150+ endpoints
export const CURATED_TOOLS: Record<string, CuratedTool> = {
  lookup_dns: {
    path: "/v1/dns/lookup",
    method: "post",
    title: "DNS Lookup",
    description:
      "Query DNS records (A, AAAA, MX, TXT, CNAME, NS) for a domain. " +
      "Use when you need to check DNS configuration or troubleshoot domain resolution.",
    annotations: { readOnlyHint: true, openWorldHint: true },
  },
  dev_hash: {
    path: "/v1/hash",
    method: "post",
    title: "Hash Text",
    description:
      "Generate a hash (MD5, SHA-1, SHA-256, SHA-512) of input text. " +
      "Use for checksums, data integrity, or fingerprinting.",
    annotations: { readOnlyHint: true },
  },
  // ... 47 more curated tools
};

As ferramentas que não foram bem-sucedidas: operações em lote com grandes cargas úteis (geração de PDF a partir de HTML), ferramentas que retornam dados binários (imagem de código QR, captura de tela) e ferramentas com sobreposição funcionalidade (três endpoints de hash diferentes reunidos em um). Cada ferramenta que você adiciona custa tokens. Trate seu manifesto MCP como um produto, não como um espelho de seus documentos de API.

2. Escreva descrições de ferramentas que ajudem o modelo a escolher corretamente

O modelo lê a descrição da sua ferramenta para decidir se deve chamá-la. Uma descrição vaga como "Será que Coisas de DNS" força o modelo a adivinhar. Uma descrição repleta de detalhes de implementação desperdiça tokens em informações que o modelo não precisa.

O padrão que funciona: uma frase começando com um verbo que indica o que a ferramenta faz, seguida por uma segunda frase começando com "Usar quando" que descreve a condição de acionamento.

Descrições ruins

// Bad: vague, no trigger condition
{
  name: "dns",
  description: "Does DNS stuff"
}

// Bad: too long, includes implementation details
{
  name: "dns_lookup_tool",
  description: "This tool uses the DNS-over-HTTPS protocol to query Cloudflare's 1.1.1.1 resolver via a GET request to https://cloudflare-dns.com/dns-query with an Accept header of application/dns-json. It supports A, AAAA, MX, TXT, CNAME, and NS record types and returns the raw DNS response parsed into JSON format."
}

Boas descrições

// Good: verb-first, one sentence what + one sentence when
{
  name: "lookup_dns",
  description:
    "Query DNS records (A, AAAA, MX, TXT, CNAME, NS) for a domain. " +
    "Use when you need to check DNS configuration or troubleshoot domain resolution."
}

// Good: specific about capabilities and trigger condition
{
  name: "security_pii_detect",
  description:
    "Scan text for personal identifiable information (emails, phones, SSNs, credit cards). " +
    "Use when you need to audit user input or log output for sensitive data before storage."
}

A primeira frase é para seleção de ferramenta: ela diz ao modelo o que a ferramenta faz e o que ela fornece aceita. A segunda frase é para desambiguação: quando duas ferramentas podem corresponder, a cláusula "Usar quando" ajuda o modelo a escolher o caminho certo.

Todas as 49 ferramentas do servidor MCP do Botoi seguem esse padrão. O resultado: os modelos escolhem consistentemente o ferramenta correta na primeira tentativa, mesmo quando várias ferramentas têm capacidades sobrepostas (por exemplo, lookup_email vs. lookup_dns para verificar registros MX).

3. Use anotações de ferramentas

A especificação MCP define quatro dicas de anotação: readOnlyHint, destructiveHint, idempotentHint, e openWorldHint. A maioria dos servidores os ignora. Modelos e clientes que respeitam essas dicas tomam decisões mais seguras: eles não chamarão ferramentas destrutivas sem confirmação, eles tentarão novamente as ferramentas idempotentes em caso de falha e avisarão os usuários antes que as ferramentas contactar serviços externos.

// Annotations from Botoi's curated-tools.ts
lookup_dns: {
  path: "/v1/dns/lookup",
  annotations: {
    readOnlyHint: true,    // reads data, changes nothing
    openWorldHint: true,   // contacts external DNS servers
  },
},

storage_paste_create: {
  path: "/v1/paste/create",
  annotations: {
    destructiveHint: true,   // creates new data
    idempotentHint: false,   // each call creates a new paste
  },
},

dev_hash: {
  path: "/v1/hash",
  annotations: {
    readOnlyHint: true,      // pure computation
    idempotentHint: true,    // same input = same output
  },
},

As anotações não custam quase nada em termos de tamanho do manifesto, mas dão aos clientes e modelos a oportunidade de metadados necessários para planejar fluxos de trabalho de várias etapas com segurança. Defina-os em todas as ferramentas.

4. Torne-se sem estado com HTTP Streamable

O transporte SSE (Server-Sent Events) está obsoleto na especificação MCP. Exigia persistência conexões, gerenciamento de sessão e lógica de reconexão. HTTP streamável substitui-o pelo padrão Solicitações HTTP POST transportando cargas JSON-RPC 2.0. Nenhuma conexão persistente. Nenhum estado de sessão. Funciona com todas as infraestruturas HTTP: CDNs, balanceadores de carga, tempos de execução de borda, plataformas sem servidor.

O servidor MCP do Botoi é executado em Cloudflare Workers. Cada solicitação cria um novo McpServer por exemplo, registra todas as 49 ferramentas, trata da solicitação e retorna. Sem ID de sessão, sem reconexão manipulador, nenhum estado para gerenciar entre solicitações.

// MCP server on Cloudflare Workers with Streamable HTTP
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import {
  WebStandardStreamableHTTPServerTransport
} from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";

app.all("/mcp", async (c) => {
  const apiKey =
    c.req.header("X-API-Key") ||
    c.req.header("Authorization")?.replace("Bearer ", "");

  const server = createMcpServer(apiKey, c.env);
  const transport = new WebStandardStreamableHTTPServerTransport();
  await server.connect(transport);
  return transport.handleRequest(c.req.raw);
});

O WebStandardStreamableHTTPServerTransport do MCP SDK funciona com qualquer tempo de execução que suporta os padrões da Web Request/Response API: Trabalhadores Cloudflare, Deno Deploy, Bun, Vercel Edge Functions e Node.js 18+. Se você estiver iniciando um novo servidor MCP em 2026, use HTTP Streamável. Se você estiver executando um servidor SSE, migre antes que os clientes abandonem o suporte.

5. Valide entradas com esquemas

As ferramentas MCP recebem JSON arbitrário dos modelos. Um modelo pode enviar onde você espera uma string, inclua campos desconhecidos ou omita parâmetros obrigatórios. Validando entradas antes da execução detectar esses erros antecipadamente e retornar feedback estruturado que o modelo pode usar para autocorreção.

A abordagem de Botoi: o schema-builder.ts módulo lê definições de caminho OpenAPI em tempo de registro e converte cada propriedade para um tipo Zod. O SDK do MCP valida entradas em relação a o esquema Zod antes da execução do manipulador de ferramentas.

// schema-builder.ts - OpenAPI to Zod conversion
import { z } from "zod";
import { paths } from "../../openapi-paths";

function mapPropertyToZod(
  prop: OpenApiProperty,
  isRequired: boolean
): z.ZodTypeAny {
  let schema: z.ZodTypeAny;

  if (prop.enum && prop.enum.length > 0) {
    schema = z.enum(prop.enum as [string, ...string[]]);
  } else {
    switch (prop.type) {
      case "number":
      case "integer":
        schema = z.number(); break;
      case "boolean":
        schema = z.boolean(); break;
      default:
        schema = z.string(); break;
    }
  }

  if (!isRequired) schema = schema.optional();
  return schema;
}

export function buildZodSchema(
  apiPath: string,
  method: "get" | "post"
): Record<string, z.ZodTypeAny> {
  const operation = getOperation(apiPath, method);
  if (!operation) return {};

  const schema = operation.requestBody?.content?.["application/json"]?.schema;
  if (!schema?.properties) return {};

  const required = new Set(schema.required ?? []);
  const result: Record<string, z.ZodTypeAny> = {};

  for (const [key, prop] of Object.entries(schema.properties)) {
    result[key] = mapPropertyToZod(prop, required.has(key));
  }

  return result;
}

O loop de registro passa o esquema gerado como inputSchema para cada ferramenta:

// server.ts - register tools with Zod schemas
for (const [toolName, tool] of Object.entries(CURATED_TOOLS)) {
  const zodSchema = buildZodSchema(tool.path, tool.method);

  server.registerTool(toolName, {
    title: tool.title,
    description: tool.description,
    inputSchema: zodSchema,
    annotations: tool.annotations,
  }, async (args: Record<string, unknown>) => {
    return callApi(tool.path, tool.method, args, apiKey, env);
  });
}

Isso significa que cada ferramenta obtém validação de entrada gratuitamente. Se o modelo enviar um número inteiro onde uma string é esperado, o SDK do MCP retornará um erro estruturado antes da execução do código do manipulador. O modelo vê o erro, corrige a entrada e tenta novamente.

6. Retornar erros estruturados sobre os quais o modelo pode raciocinar

Quando uma ferramenta falha, o modelo precisa de informações suficientes para se recuperar. “Algo deu errado” é inútil. Um erro estruturado com o nome do campo, o que era esperado e o que foi recebido dá ao modelo uma limpe o caminho para tentar novamente com a entrada corrigida.

Resposta de erro incorreta

// Bad: the model can't fix this
{
  "content": [{ "type": "text", "text": "Something went wrong" }],
  "isError": true
}

Boa resposta ao erro

// Structured error the model can reason about
{
  "content": [
    {
      "type": "text",
      "text": "{\\n  \\"error\\": \\"validation_error\\",\\n  \\"message\\": \\"Invalid record type\\",\\n  \\"field\\": \\"type\\",\\n  \\"expected\\": [\\"A\\", \\"AAAA\\", \\"MX\\", \\"TXT\\", \\"CNAME\\", \\"NS\\"],\\n  \\"received\\": \\"INVALID\\"\\n}"
    }
  ],
  "isError": true
}

Botoi's callApi wrapper captura o erro estruturado da API REST subjacente e passa para a resposta do MCP com isError: true:

// server.ts - API call wrapper with structured errors
async function callApi(
  path: string,
  method: string,
  body: unknown,
  apiKey: string | undefined,
  env: Env
) {
  const headers: Record<string, string> = {
    "Content-Type": "application/json",
  };
  if (apiKey) headers["X-API-Key"] = apiKey;

  const req = new Request(\`http://internal\${path}\`, {
    method: method.toUpperCase(),
    headers,
    body: method === "post" ? JSON.stringify(body) : undefined,
  });

  const res = await appFetcher(req, env);
  const json = await res.json();

  if (!json.success) {
    return {
      content: [{
        type: "text",
        text: JSON.stringify(json.error, null, 2),
      }],
      isError: true,
    };
  }

  return {
    content: [{
      type: "text",
      text: JSON.stringify(json.data, null, 2),
    }],
  };
}

O detalhe principal: o isError: true flag informa ao modelo que a invocação da ferramenta falhou. O JSON estruturado no text campo diz o porquê. Modelos treinados em padrões de uso de ferramentas irá ler o erro, identificar o campo do problema e tentar novamente com um valor corrigido. Erro genérico strings forçam o modelo a adivinhar ou desistir.

7. Adicione autenticação sem prejudicar a experiência do desenvolvedor

Os servidores MCP precisam de autenticação. A especificação suporta OAuth 2.1 para fluxos de autorização completos, mas a maioria as ferramentas do desenvolvedor funcionam bem com o encaminhamento de chave de API. O desenvolvedor adiciona sua chave ao cliente MCP configurar uma vez; o servidor o extrai dos cabeçalhos da solicitação e o repassa para cada chamada de API.

Aqui está a configuração do cliente para Claude Desktop com uma chave de API:

// Client config: Claude Desktop
{
  "mcpServers": {
    "botoi": {
      "type": "streamable-http",
      "url": "https://api.botoi.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

O servidor extrai a chave do Authorization cabeçalho ou o X-API-Key cabeçalho e o encaminha para todas as chamadas de API internas:

// server.ts - extract API key from MCP request headers
app.all("/mcp", async (c) => {
  const apiKey =
    c.req.header("X-API-Key") ||
    c.req.header("Authorization")?.replace("Bearer ", "");

  // Pass the key through to every API call
  const server = createMcpServer(apiKey, c.env);
  const transport = new WebStandardStreamableHTTPServerTransport();
  await server.connect(transport);
  return transport.handleRequest(c.req.raw);
});

Sem uma chave, o servidor ainda funciona. Botoi permite acesso anônimo a 5 solicitações por minuto e 100 por dia, o suficiente para uso casual durante uma sessão de codificação. Com uma chave, limita a escala ao nível de plano do desenvolvedor. Esta abordagem significa integração sem atrito (não é necessária inscrição para experimentá-la) com um caminho de atualização claro quando o uso aumentar.

Servidor MCP bom versus servidor MCP ruim

O cenário de 10.000 servidores

O crescimento de 1.000 para 10.000 servidores MCP em seis meses aconteceu porque o protocolo se estabilizou. OAuth 2.1 substituiu os padrões de autenticação ad hoc. HTTP streamável substituiu o SSE. A Fundação Linux a governança deu às empresas a confiança necessária para construir servidores de produção. SDKs em seis idiomas reduzidos a barreira à entrada.

Mas a quantidade não trouxe qualidade. A maioria desses servidores eram experimentos de fim de semana que nunca passaram o estágio "registrar todos os meus endpoints e ver o que acontece". Os servidores que os desenvolvedores usam diariamente investiu em curadoria, descrições, esquemas, tratamento de erros e autenticação. Essas cinco áreas são onde 90% da lacuna de usabilidade vive.

Se você estiver construindo um servidor MCP em 2026, a barra não será “funciona”. A barra é "o modelo escolha a ferramenta certa, entenda o erro quando for errado e recupere sem intervenção humana." As sete práticas acima levam você até lá.

O servidor MCP do Botoi está aberto para testes. Conecte-se a partir de Claude Desktop, Claude Code, Cursor, VS Code, ou Windsurf usando as configurações no Página de configuração do MCP. O manifesto completo da ferramenta é em api.botoi.com/v1/mcp/tools.json, e o Documentos da API cubra todos os pontos de extremidade por trás das ferramentas.