Существует 10 000 серверов MCP: вот что отличает хорошие серверы

1. Курировать инструменты; не сбрасывайте весь свой API

Самая большая ошибка: регистрация каждой конечной точки API как инструмента MCP. Ботой имеет более 150 конечных точек. Если бы все они были инструментами MCP, манифест инструмента перед разговором потреблял бы более 30 000 токенов. начинается. Это оставляет меньше места для реального вопроса пользователя и увеличивает вероятность того, что модель выберет неправильный инструмент и замедляет каждый запрос, поскольку модели приходится читать сотни инструментов. определения.

Регистры Ботой 49. Критерии отбора: инструменты, которыми пользуются разработчики во время сеансов кодирования (DNS поиск, декодирование JWT, генерация хэша), инструменты, создающие модели структурированного вывода, могут рассуждать о (проверка JSON, обнаружение PII) и инструменты, сохраняющие переключение контекста (кодирование Base64, метаданные URL-адреса). экстракция).

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

Инструменты, которые не попали в список: пакетные операции с большими объемами полезной нагрузки (генерация PDF из HTML), инструменты, возвращающие двоичные данные (изображение QR-кода, снимок экрана), а также инструменты с перекрытием функциональность (три разные конечные точки хеширования объединены в одну). Каждый добавляемый вами инструмент стоит жетонов. Относитесь к манифесту MCP как к продукту, а не как к зеркалу документации API.

2. Напишите описания инструментов, которые помогут правильно подобрать модель.

Модель читает описание вашего инструмента, чтобы решить, следует ли его вызывать. Расплывчатое описание типа «Действует ли DNS-штуки» заставляют модель гадать. Описание, наполненное подробностями реализации, приводит к потере токенов. об информации, которая не нужна модели.

Схема, которая работает: одно предложение, начинающееся с глагола, описывающего, что делает инструмент, за которым следует второе предложение, начинающееся с «Использовать когда», описывающее условие триггера.

Плохие описания

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

Хорошие описания

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

Первое предложение предназначено для выбора инструмента: оно сообщает модели, что делает инструмент и какие входные данные он использует. принимает. Второе предложение предназначено для устранения неоднозначности: когда два инструмента могут совпадать, пункт «Использовать, когда» помогает модели выбрать правильный вариант.

Все 49 инструментов на сервере MCP Ботоя следуют этому шаблону. Результат: модели последовательно выбирают правильный инструмент с первой попытки, даже если несколько инструментов имеют перекрывающиеся возможности (например, lookup_email против. lookup_dns для проверки записей MX).

3. Используйте аннотации инструментов

Спецификация MCP определяет четыре подсказки к аннотациям: readOnlyHint, destructiveHint, idempotentHint, и openWorldHint. Большинство серверов их игнорируют. Модели и клиенты, которые уважают эти подсказки, принимают более безопасные решения: они не будут вызывать деструктивные инструменты без подтверждения, они будут повторять попытки идемпотентных инструментов в случае неудачи и предупреждать пользователей перед инструментами, которые обратитесь в внешние службы.

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

Аннотации практически ничего не стоят с точки зрения размера манифеста, но они дают клиентам и моделям метаданные, необходимые им для безопасного планирования многоэтапных рабочих процессов. Установите их на каждый инструмент.

4. Откажитесь от сохранения состояния с помощью Streamable HTTP

Транспорт SSE (события, отправленные сервером) устарел в спецификации MCP. Это требовало настойчивого соединения, управление сеансами и логика повторного подключения. Streamable HTTP заменяет его стандартным Запросы HTTP POST, содержащие полезные данные JSON-RPC 2.0. Нет постоянного соединения. Нет состояния сеанса. Работает с любой инфраструктурой HTTP: CDN, балансировщиками нагрузки, периферийными средами выполнения, бессерверными платформами.

Сервер MCP Botoi работает на Cloudflare Workers. Каждый запрос создает новый McpServer экземпляр, регистрирует все 49 инструментов, обрабатывает запрос и возвращает результат. Нет идентификатора сеанса, нет переподключения обработчик, нет состояния для управления между запросами.

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

The WebStandardStreamableHTTPServerTransport из MCP SDK работает с любой средой выполнения который поддерживает веб-стандарты Request/Response API: работники Cloudflare, Deno Deploy, Bun, Vercel Edge Functions и Node.js 18+. Если вы запускаете новый сервер MCP в 2026 года используйте потоковый HTTP. Если вы используете сервер SSE, выполните миграцию до того, как клиенты прекратят поддержку.

5. Проверка входных данных с помощью схем

Инструменты MCP получают произвольный JSON от моделей. Модель может отправить где вы ожидаете строку, включите неизвестные поля или опустите обязательные параметры. Проверка входных данных прежде чем выполнение выявляет эти ошибки заранее и возвращает структурированную обратную связь, которую модель может использовать для самостоятельно исправить.

Подход Ботоя: schema-builder.ts модуль считывает определения путей OpenAPI по адресу время регистрации и преобразует каждое свойство в тип Zod. MCP SDK проверяет входные данные на соответствие схему Zod перед запуском обработчика инструмента.

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

Цикл регистрации передает сгенерированную схему как inputSchema для каждого инструмента:

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

Это означает, что каждый инструмент получает проверку ввода бесплатно. Если модель отправляет целое число, где строка ожидается, MCP SDK возвращает структурированную ошибку до запуска кода обработчика. Модель видит ошибку, исправляет ввод и повторяет попытку.

6. Возвращает структурированные ошибки, которые может выявить модель.

Когда инструмент выходит из строя, модели требуется достаточно информации для восстановления. «Что-то пошло не так» бесполезно. Структурированная ошибка с именем поля, ожидаемым и полученным значением дает модели очистить путь для повторной попытки с исправленным вводом.

Плохой ответ об ошибке

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

Хороший ответ на ошибку

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

Ботоя callApi оболочка фиксирует структурированную ошибку из базового REST API и передает его в ответ MCP с помощью 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),
    }],
  };
}

Ключевая деталь: isError: true флаг сообщает модели, что вызов инструмента не удался. Структурированный JSON в text field tells it why. Модели, обученные шаблонам использования инструментов прочитает ошибку, определит проблемное поле и повторит попытку с исправленным значением. Общая ошибка струны заставляют модель гадать или сдаваться.

7. Добавьте аутентификацию, не нарушая возможности разработчика

Серверам MCP необходима аутентификация. Спецификация поддерживает OAuth 2.1 для полных потоков авторизации, но большинство инструменты разработчика отлично работают с переадресацией ключей API. Разработчик добавляет свой ключ в клиент MCP. настроить один раз; сервер извлекает его из заголовков запроса и передает каждому вызову API.

Вот конфигурация клиента для Claude Desktop с ключом API:

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

Сервер извлекает ключ либо из Authorization заголовок или X-API-Key заголовок, а затем перенаправляет его на каждый внутренний вызов API:

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

Без ключа сервер все равно работает. Botoi обеспечивает анонимный доступ со скоростью 5 запросов в минуту и 100 в день, чего достаточно для повседневного использования во время сеанса кодирования. С помощью ключа ограничивает масштаб до уровень плана разработчика. Этот подход означает нулевую адаптацию (для того, чтобы попробовать его, регистрация не требуется). с четким путем обновления по мере роста использования.

Хороший сервер MCP против плохого сервера MCP

Ландшафт из 10 000 серверов

Рост с 1000 до 10 000 серверов MCP за шесть месяцев произошел благодаря стабилизации протокола. OAuth 2.1 заменил специальные шаблоны аутентификации. Потоковый HTTP заменил SSE. Фонд Linux управление дало предприятиям уверенность в необходимости создания производственных серверов. SDK на шести языках снижены барьер входа.

Но количество не привело к качеству. Большинство из этих серверов были экспериментами выходного дня, которые так и не были доведены до конца. этап «зарегистрируйте все мои конечные точки и посмотрите, что произойдет». Серверы, которые разработчики используют ежедневно вложено в курирование, описания, схемы, обработку ошибок и аутентификацию. Those five areas are where 90% разрыв в юзабилити живет.

Если вы создаете сервер MCP в 2026 году, полоска не будет показывать «работает ли он». Полоса "делает ли модель выбрать правильный инструмент, понять ошибку, если он выбран неправильно, и восстановиться без вмешательства человека». Семь приведенных выше практик помогут вам в этом.

Сервер MCP Ботоя открыт для тестирования. Подключайтесь с рабочего стола Claude, Claude Code, Cursor, VS Code, или виндсерфинг, используя настройки на Страница настройки MCP. Полный манифест инструмента: в api.botoi.com/v1/mcp/tools.json, и Документация по API охватить каждую конечную точку инструментов.