Es gibt 10.000 MCP-Server: Das unterscheidet die Guten

1. Werkzeuge kuratieren; Löschen Sie nicht Ihre gesamte API

Der größte Fehler: jeden API-Endpunkt als MCP-Tool registrieren. Botoi hat mehr als 150 Endpunkte. Wenn es sich bei allen um MCP-Tools handeln würde, würde das Tool-Manifest vor einer Konversation mehr als 30.000 Token verbrauchen beginnt. Das lässt weniger Raum für die eigentliche Frage des Benutzers und erhöht die Chance, dass das Modell die Frage auswählt falsches Tool und verlangsamt jede Anfrage, da das Modell Hunderte von Tools durchlesen muss Definitionen.

Botoi registriert 49. Die Auswahlkriterien: Tools, nach denen Entwickler während Coding-Sitzungen greifen (DNS (Suche, JWT-Dekodierung, Hash-Generierung) können Tools, die strukturierte Ausgabemodelle erzeugen, darüber nachdenken (JSON-Validierung, PII-Erkennung) und Tools, die einen Kontextwechsel ersparen (Base64-Kodierung, URL-Metadaten). Extraktion).

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

Die Tools, die es nicht geschafft haben: Batch-Operationen mit großen Nutzlasten (PDF-Generierung aus HTML), Tools, die Binärdaten zurückgeben (QR-Code-Bild, Screenshot-Erfassung) und Tools mit Überlappung Funktionalität (drei verschiedene Hash-Endpunkte zu einem zusammengefasst). Jedes hinzugefügte Werkzeug kostet Token. Behandeln Sie Ihr MCP-Manifest wie ein Produkt, nicht wie einen Spiegel Ihrer API-Dokumente.

2. Write tool descriptions that help the model pick correctly

The model reads your tool description to decide whether to call it. Eine vage Beschreibung wie „Tut „DNS stuff“ zwingt das Modell zum Raten. A description stuffed with implementation details wastes tokens auf Informationen, die das Modell nicht benötigt.

Das Muster, das funktioniert: ein Satz, der mit einem Verb beginnt, das angibt, was das Tool tut, gefolgt von ein zweiter Satz, der mit „Use when“ beginnt und die Auslösebedingung beschreibt.

Schlechte Beschreibungen

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

Gute Beschreibungen

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

Der erste Satz dient der Werkzeugauswahl: Er teilt dem Modell mit, was das Werkzeug tut und welche Eingaben es macht akzeptiert. Der zweite Satz dient der Begriffsklärung: Wenn zwei Tools übereinstimmen könnten, wird die Klausel „Verwenden, wenn“ verwendet hilft dem Modell, das Richtige auszuwählen.

Alle 49 Tools im MCP-Server von Botoi folgen diesem Muster. Das Ergebnis: Models wählen konsequent das aus Richtiges Werkzeug beim ersten Versuch, auch wenn mehrere Werkzeuge überlappende Funktionen haben (z. B. lookup_email vs. lookup_dns zur Überprüfung von MX-Records).

3. Verwenden Sie Werkzeuganmerkungen

Die MCP-Spezifikation definiert vier Anmerkungshinweise: readOnlyHint, destructiveHint, idempotentHint, Und openWorldHint. Die meisten Server ignorieren sie. Modelle und clients that respect these hints make safer decisions: they won't call destructive tools without confirmation, they'll retry idempotent tools on failure, and they'll warn users before tools that Wenden Sie sich an externe Dienste.

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

Anmerkungen kosten in Bezug auf die Manifestgröße fast nichts, bieten Kunden und Modellen jedoch die Möglichkeit Metadaten, die sie benötigen, um mehrstufige Arbeitsabläufe sicher zu planen. Setzen Sie sie auf jedes Werkzeug.

4. Werden Sie zustandslos mit Streamable HTTP

Der SSE-Transport (Server-Sent Events) ist in der MCP-Spezifikation veraltet. Es erforderte Ausdauer Verbindungen, Sitzungsverwaltung und Wiederverbindungslogik. Streamable HTTP ersetzt es durch Standard HTTP-POST-Anfragen mit JSON-RPC 2.0-Nutzlasten. Keine dauerhafte Verbindung. Kein Sitzungsstatus. Funktioniert mit jeder HTTP-Infrastruktur: CDNs, Load Balancer, Edge Runtimes, serverlose Plattformen.

Der MCP-Server von Botoi läuft auf Cloudflare Workers. Jede Anfrage erzeugt eine neue McpServer In der Instanz werden alle 49 Tools registriert, die Anfrage bearbeitet und zurückgegeben. Keine Sitzungs-ID, keine erneute Verbindung Handler, kein zu verwaltender Status zwischen Anforderungen.

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

Der WebStandardStreamableHTTPServerTransport aus dem MCP SDK funktioniert mit jeder Laufzeit das die Webstandards unterstützt Request/Response API: Cloudflare Workers, Deno Deploy, Bun, Vercel Edge Functions und Node.js 18+. Wenn Sie einen neuen MCP-Server starten 2026, verwenden Sie Streamable HTTP. Wenn Sie einen SSE-Server betreiben, migrieren Sie, bevor die Clients die Unterstützung einstellen.

5. Validieren Sie Eingaben mit Schemata

MCP-Tools empfangen beliebiges JSON von Modellen. Ein Modell kann senden wo Sie eine Zeichenfolge erwarten, unbekannte Felder einschließen oder erforderliche Parameter weglassen. Eingaben validieren Vor der Ausführung werden diese Fehler frühzeitig erkannt und strukturiertes Feedback zurückgegeben, das das Modell verwenden kann Selbstkorrektur.

Botois Ansatz: der schema-builder.ts Modul liest OpenAPI-Pfaddefinitionen unter Registrierungszeit und wandelt jede Eigenschaft in einen Zod-Typ um. Das MCP SDK validiert Eingaben anhand das Zod-Schema, bevor der Tool-Handler ausgeführt wird.

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

Die Registrierungsschleife übergibt das generierte Schema als inputSchema für jedes Werkzeug:

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

Das bedeutet, dass jedes Tool eine kostenlose Eingabevalidierung erhält. Wenn das Modell eine Ganzzahl sendet, bei der es sich um eine Zeichenfolge handelt erwartet wird, gibt das MCP SDK einen strukturierten Fehler zurück, bevor Ihr Handlercode ausgeführt wird. Das Modell sieht Beheben Sie den Fehler, korrigieren Sie die Eingabe und versuchen Sie es erneut.

6. Geben Sie strukturierte Fehler zurück, über die das Modell nachdenken kann

Wenn ein Tool ausfällt, benötigt das Modell genügend Informationen zur Wiederherstellung. „Etwas ist schief gelaufen“ ist nutzlos. Ein strukturierter Fehler mit dem Feldnamen, dem, was erwartet wurde und dem, was empfangen wurde, gibt dem Modell eine Freier Pfad zum erneuten Versuch mit korrigierter Eingabe.

Schlechte Fehlerantwort

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

Gute Fehlerreaktion

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

Botois callApi Der Wrapper erfasst den strukturierten Fehler von der zugrunde liegenden REST-API und leitet es an die MCP-Antwort weiter 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),
    }],
  };
}

Das entscheidende Detail: das isError: true Flag teilt dem Modell mit, dass der Toolaufruf fehlgeschlagen ist. Der strukturierte JSON im text Das Feld sagt ihm, warum. Modelle, die anhand von Werkzeugnutzungsmustern trainiert wurden liest den Fehler, identifiziert das Problemfeld und versucht es erneut mit einem korrigierten Wert. Allgemeiner Fehler Zeichenfolgen zwingen das Modell zum Raten oder Aufgeben.

7. Fügen Sie die Authentifizierung hinzu, ohne die Entwicklererfahrung zu beeinträchtigen

MCP-Server benötigen eine Authentifizierung. Die Spezifikation unterstützt OAuth 2.1 für vollständige Autorisierungsflüsse, aber die meisten Entwicklertools funktionieren gut mit der Weiterleitung von API-Schlüsseln. Der Entwickler fügt seinen Schlüssel zum MCP-Client hinzu einmal konfigurieren; Der Server extrahiert es aus den Anforderungsheadern und leitet es an jeden API-Aufruf weiter.

Hier ist die Client-Konfiguration für Claude Desktop mit einem API-Schlüssel:

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

Der Server extrahiert den Schlüssel entweder aus dem Authorization Kopfzeile oder die X-API-Key Header und leitet ihn dann an jeden internen API-Aufruf weiter:

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

Ohne Schlüssel funktioniert der Server weiterhin. Botoi ermöglicht anonymen Zugriff mit 5 Anfragen pro Minute und 100 pro Tag, genug für den gelegentlichen Gebrauch während einer Programmiersitzung. Mit einem Schlüssel wird der Maßstab auf die begrenzt Planstufe des Entwicklers. Dieser Ansatz ermöglicht ein reibungsloses Onboarding (keine Anmeldung erforderlich, um es auszuprobieren). mit einem klaren Upgrade-Pfad, wenn die Nutzung zunimmt.

Guter MCP-Server vs. schlechter MCP-Server

Die 10.000-Server-Landschaft

Das Wachstum von 1.000 auf 10.000 MCP-Server in sechs Monaten erfolgte, weil sich das Protokoll stabilisierte. OAuth 2.1 ersetzte die Ad-hoc-Authentifizierungsmuster. Streamable HTTP ersetzte SSE. Die Linux Foundation Governance gab Unternehmen das Vertrauen, Produktionsserver zu bauen. SDKs in sechs Sprachen gesenkt die Eintrittsbarriere.

Aber Quantität brachte nicht Qualität. Die meisten dieser Server waren Wochenendexperimente, die nie zustande kamen die Phase „Alle meine Endpunkte registrieren und sehen, was passiert“. Die Server, die Entwickler täglich nutzen investiert in Kuration, Beschreibungen, Schemata, Fehlerbehandlung und Authentifizierung. In diesen fünf Bereichen sind 90 % von der Usability-Lücke lebt.

Wenn Sie im Jahr 2026 einen MCP-Server bauen, lautet die Messlatte nicht „funktioniert es“. Die Leiste lautet „Tut das Modell“. Wählen Sie das richtige Werkzeug aus, verstehen Sie den Fehler, wenn er falsch ausgewählt wird, und beheben Sie die Fehler ohne menschliches Eingreifen.“ Die sieben oben genannten Übungen bringen Sie dorthin.

Der MCP-Server von Botoi ist zum Testen geöffnet. Verbinden Sie sich über Claude Desktop, Claude Code, Cursor, VS Code, oder Windsurfen mit den Konfigurationen auf der MCP-Setup-Seite. Das vollständige Tool-Manifest finden Sie hier bei api.botoi.com/v1/mcp/tools.json, und die API-Dokumente Decken Sie jeden Endpunkt hinter den Tools ab.