MCP Server Card

Что такое MCP Server Card?

MCP Server Card — JSON-манифест по адресу /.well-known/mcp/server-card.json, описывающий ваш MCP-сервер: имя, версию, транспорт, capabilities. Позволяет AI-агентам автоматически обнаружить MCP-сервер по домену без ручной настройки.

MCP (Model Context Protocol) — открытый протокол Anthropic для стандартизации взаимодействия AI-агентов с инструментами и данными. Агент «подключается» к серверу и получает набор tools, resources и prompts.

Аналогия: если ваш API — магазин, MCP Server Card — вывеска с часами работы и ассортиментом.

Зачем нужна MCP Server Card?

До стандартизации MCP discovery каждая интеграция требовала ручной настройки: разработчик вручную указывал URL и описывал инструменты. При большом числе агентов и серверов это не масштабируется.

MCP Server Card решает задачу federated tool discovery:

• Автоматическая конфигурация — агент проверяет /.well-known/mcp/server-card.json и сразу видит доступные инструменты
• Версионирование — клиент проверяет версию протокола и совместимость
• Безопасность — карточка описывает требования аутентификации (OAuth, API-key)

Особенно нужно: SaaS с API, DevTools, корпоративные базы знаний, любой сервис, предназначенный для AI-агентов.

Как реализовать MCP Server Card?

Минимальная карточка:

{
  "serverInfo": {
    "name": "My Service MCP",
    "version": "1.0.0"
  },
  "transport": {
    "type": "http",
    "endpoint": "https://api.example.com/mcp"
  },
  "capabilities": {
    "tools": true,
    "resources": false,
    "prompts": false
  }
}

Расширенный вариант с аутентификацией:

{
  "serverInfo": {
    "name": "Example CRM MCP Server",
    "version": "1.2.0",
    "description": "CRM data and workflow automation via MCP",
    "contact": {
      "email": "mcp@example.com",
      "url": "https://example.com/mcp-docs"
    }
  },
  "transport": {
    "type": "http",
    "endpoint": "https://api.example.com/mcp/v1",
    "protocol": "MCP/1.0"
  },
  "capabilities": {
    "tools": true,
    "resources": true,
    "prompts": true
  },
  "authentication": {
    "required": true,
    "methods": ["oauth2", "api-key"],
    "oauthEndpoint": "https://auth.example.com/.well-known/openid-configuration"
  },
  "rateLimit": {
    "requestsPerMinute": 60,
    "headerName": "RateLimit-Remaining"
  }
}

Публикация в Astro:

// src/pages/.well-known/mcp/server-card.json.ts
export async function GET() {
  const card = {
    serverInfo: { name: 'My MCP', version: '1.0.0' },
    transport: { type: 'http', endpoint: 'https://example.com/api/mcp' },
    capabilities: { tools: true }
  };
  return new Response(JSON.stringify(card), {
    headers: { 'Content-Type': 'application/json' }
  });
}

Для Nginx (статический файл):

location = /.well-known/mcp/server-card.json {
    alias /var/www/well-known/mcp-server-card.json;
    add_header Content-Type application/json;
    add_header Access-Control-Allow-Origin *;
}

Как мы проверяем MCP Server Card?

Сканер последовательно проверяет три пути (в порядке приоритета):

1. /.well-known/mcp/server-card.json
2. /.well-known/mcp/server-cards.json
3. /.well-known/mcp.json

Для каждого пути выполняется:

1. HTTP-статус — если ни один не вернул 200 → fail
2. Валидный JSON — тело парсится без ошибок
3. Обязательные поля — присутствуют serverInfo.name, serverInfo.version
4. Транспорт — присутствуют transport.type и transport.endpoint
5. Capabilities — присутствует объект capabilities

pass — хотя бы один путь вернул HTTP 200 с корректным JSON и обязательными полями. fail — все пути недоступны или JSON некорректен.