Existen 10.000 servidores MCP: esto es lo que separa a los buenos

1. Seleccionar herramientas; no descartes toda tu API

El mayor error: registrar cada punto final API como una herramienta MCP. Botoi tiene más de 150 puntos finales. Si todas fueran herramientas MCP, el manifiesto de la herramienta consumiría más de 30.000 tokens antes de una conversación. comienza. Eso deja menos espacio para la pregunta real del usuario, aumenta la posibilidad de que el modelo elija la herramienta incorrecta y ralentiza cada solicitud porque el modelo tiene que leer cientos de herramientas definiciones.

Botoi registra 49. Los criterios de selección: herramientas que los desarrolladores utilizan durante las sesiones de codificación (DNS búsqueda, decodificación JWT, generación de hash), las herramientas que producen modelos de salida estructurados pueden razonar sobre (validación JSON, detección de PII) y herramientas que guardan un cambio de contexto (codificación Base64, metadatos de URL extracción).

// 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
};

Las herramientas que no tuvieron éxito: operaciones por lotes con grandes cargas útiles (generación de PDF a partir de HTML), herramientas que devuelven datos binarios (imagen de código QR, captura de pantalla) y herramientas con superposición funcionalidad (tres puntos finales hash diferentes colapsados en uno). Cada herramienta que agregas cuesta tokens. Trate su manifiesto MCP como un producto, no como un espejo de sus documentos API.

2. Escriba descripciones de herramientas que ayuden al modelo a elegir correctamente.

El modelo lee la descripción de su herramienta para decidir si llamarla. Una descripción vaga como "¿Tiene Cosas de DNS" obliga al modelo a adivinar. Una descripción repleta de detalles de implementación desperdicia tokens en información que el modelo no necesita.

El patrón que funciona: una oración que comienza con un verbo que indica lo que hace la herramienta, seguida de una segunda oración que comienza con "Usar cuando" que describe la condición de activación.

Malas descripciones

// 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."
}

Buenas descripciones

// 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."
}

La primera oración es para la selección de herramientas: le dice al modelo qué hace la herramienta y qué entradas recibe. acepta. La segunda oración es para desambiguación: cuando dos herramientas pueden coincidir, la cláusula "Usar cuando" ayuda al modelo a elegir el correcto.

Las 49 herramientas del servidor MCP de Botoi siguen este patrón. El resultado: los modelos eligen consistentemente herramienta correcta en el primer intento, incluso cuando varias herramientas tienen capacidades superpuestas (por ejemplo, lookup_email vs. lookup_dns para comprobar registros MX).

3. Utilice anotaciones de herramientas

La especificación MCP define cuatro sugerencias de anotaciones: readOnlyHint, destructiveHint, idempotentHint, y openWorldHint. La mayoría de los servidores los ignoran. Modelos y Los clientes que respetan estos consejos toman decisiones más seguras: no llamarán a herramientas destructivas sin confirmación, volverán a intentar herramientas idempotentes en caso de falla y advertirán a los usuarios antes de que las herramientas contactar con servicios 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
  },
},

Las anotaciones no cuestan casi nada en términos de tamaño del manifiesto, pero brindan a los clientes y modelos la metadatos que necesitan para planificar flujos de trabajo de varios pasos de forma segura. Colóquelos en cada herramienta.

4. Vaya sin estado con HTTP Streamable

El transporte SSE (Eventos enviados por el servidor) está obsoleto en la especificación MCP. Se requirió perseverancia conexiones, gestión de sesiones y lógica de reconexión. Streamable HTTP lo reemplaza con estándar Solicitudes HTTP POST que transportan cargas útiles JSON-RPC 2.0. Sin conexión persistente. Sin estado de sesión. obras con cada infraestructura HTTP: CDN, balanceadores de carga, tiempos de ejecución perimetrales, plataformas sin servidor.

El servidor MCP de Botoi se ejecuta en Cloudflare Workers. Cada solicitud crea una nueva McpServer Por ejemplo, registra las 49 herramientas, maneja la solicitud y regresa. Sin ID de sesión, sin reconexión controlador, no hay estado para administrar entre solicitudes.

// 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);
});

La WebStandardStreamableHTTPServerTransport del MCP SDK funciona con cualquier tiempo de ejecución que soporta los Estándares Web Request/Response API: trabajadores de Cloudflare, Deno Deploy, Bun, Vercel Edge Functions y Node.js 18+. Si está iniciando un nuevo servidor MCP en 2026, utilice HTTP transmitible. Si está ejecutando un servidor SSE, migre antes de que los clientes dejen de admitirlo.

5. Validar entradas con esquemas

Las herramientas MCP reciben JSON arbitrario de los modelos. Un modelo puede enviar donde espera una cadena, incluye campos desconocidos u omite los parámetros requeridos. Validar entradas antes de la ejecución detecta estos errores temprano y devuelve retroalimentación estructurada que el modelo puede usar para autocorregirse.

El enfoque de Botoi: el schema-builder.ts El módulo lee las definiciones de ruta de OpenAPI en tiempo de registro y convierte cada propiedad a un tipo Zod. El SDK de MCP valida las entradas contra el esquema Zod antes de que se ejecute el controlador de herramientas.

// 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;
}

El bucle de registro pasa el esquema generado como inputSchema para cada herramienta:

// 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);
  });
}

Esto significa que cada herramienta obtiene validación de entrada de forma gratuita. Si el modelo envía un número entero donde una cadena Como se espera, el SDK de MCP devuelve un error estructurado antes de que se ejecute el código del controlador. El modelo ve el error, corrige la entrada y vuelve a intentarlo.

6. Devolver errores estructurados sobre los que el modelo puede razonar

Cuando una herramienta falla, el modelo necesita suficiente información para recuperarse. "Algo salió mal" es inútil. Un error estructurado con el nombre del campo, lo que se esperaba y lo que se recibió le da al modelo una ruta clara para volver a intentarlo con la entrada corregida.

Mala respuesta de error

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

Buena respuesta de error

// 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 El contenedor captura el error estructurado de la API REST subyacente y lo pasa a la respuesta de MCP con 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),
    }],
  };
}

El detalle clave: el isError: true El indicador le dice al modelo que la invocación de la herramienta falló. El JSON estructurado en el text El campo le dice por qué. Modelos entrenados en patrones de uso de herramientas. leerá el error, identificará el campo del problema y volverá a intentarlo con un valor corregido. error genérico Las cuerdas obligan al modelo a adivinar o darse por vencido.

7. Agregue autenticación sin alterar la experiencia del desarrollador.

Los servidores MCP necesitan autenticación. La especificación admite OAuth 2.1 para flujos de autorización completos, pero la mayoría Las herramientas de desarrollo funcionan bien con el reenvío de claves API. El desarrollador agrega su clave al cliente MCP configurar una vez; el servidor lo extrae de los encabezados de solicitud y lo pasa a cada llamada a la API.

Aquí está la configuración del cliente para Claude Desktop con una clave API:

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

El servidor extrae la clave del Authorization encabezado o el X-API-Key encabezado, luego lo reenvía a cada llamada API interna:

// 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);
});

Sin clave, el servidor sigue funcionando. Botoi permite el acceso anónimo a 5 solicitudes por minuto y 100 por día, suficiente para uso ocasional durante una sesión de codificación. Con una llave, limita la escala al nivel del plan del desarrollador. Este enfoque significa una incorporación sin fricciones (no es necesario registrarse para probarlo) con una ruta de actualización clara cuando el uso aumenta.

Buen servidor MCP versus servidor MCP malo

El panorama de los 10.000 servidores

El crecimiento de 1000 a 10 000 servidores MCP en seis meses se produjo porque el protocolo se estabilizó. OAuth 2.1 reemplazó los patrones de autenticación ad-hoc. HTTP transmitible reemplazó a SSE. La Fundación Linux La gobernanza dio a las empresas la confianza para construir servidores de producción. SDK en seis idiomas reducidos la barrera de entrada.

Pero la cantidad no trajo calidad. La mayoría de esos servidores fueron experimentos de fin de semana que nunca pasaron la etapa "registrar todos mis puntos finales y ver qué sucede". Los servidores que los desarrolladores utilizan a diario invertido en curación, descripciones, esquemas, manejo de errores y autenticación. Esas cinco áreas son donde el 90% de la brecha de usabilidad vive.

Si está construyendo un servidor MCP en 2026, la barra no es "funciona". La barra es "¿el modelo Elija la herramienta adecuada, comprenda el error cuando se selecciona incorrectamente y recupérese sin intervención humana". Las siete prácticas anteriores te llevarán allí.

El servidor MCP de Botoi está abierto para pruebas. Conéctese desde Claude Desktop, Claude Code, Cursor, VS Code, o Windsurf usando las configuraciones en el Página de configuración de MCP. El manifiesto completo de la herramienta es en api.botoi.com/v1/mcp/tools.json, y el Documentos API cubra todos los puntos finales detrás de las herramientas.