# 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?

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

```json
{
  "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
  }
}
```

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

```json
{
  "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:**

```typescript
// 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 (статический файл):**

```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 некорректен.

[← Все термины глоссария](/glossary)