# MCP-сервер AgentOS

Адрес – `https://aos.edgelab.space/mcp`, транспорт – **Streamable HTTP** без сессий: каждый запрос – один JSON-RPC 2.0 объект, ответ – JSON. Авторизация – OAuth access token или персональный API-ключ в `Authorization: Bearer …`; cookie кабинета и токен Mini App не подходят. Отдельных MCP resources и prompts нет – только [инструменты](/docs/mcp/tools).

| Параметр | Значение |
| --- | --- |
| URL | `https://aos.edgelab.space/mcp` |
| Имя сервера | `agentos` (`serverInfo.title`: AgentOS) |
| Транспорт | Streamable HTTP, только `POST` |
| Авторизация | OAuth (authorization code + PKCE S256, DCR) или API-ключ `aos3.sk_…` |
| Инструменты | [Список и права](/docs/mcp/tools) |

Пошаговое подключение с готовыми командами – в [Быстром старте](/docs/quickstart#3-подключите-mcp).

## Подключение за 1 минуту

> [!TIP]
> Выберите клиент и раскройте инструкцию. Для Claude.ai и ChatGPT используется OAuth с DCR; для CLI доступны персональные API-ключи.

**Claude.ai**

Откройте Connectors → Add custom connector (в новых версиях интерфейса Customize → Connectors), задайте имя `AgentOS` и URL `https://aos.edgelab.space/mcp`. Выберите OAuth-вход и автоматическую регистрацию клиента (**Register automatically / DCR**): AgentOS не поддерживает published identity / CIMD. Нажмите Connect, войдите по коду из почты в открывшейся вкладке (или выберите другой способ входа) и разрешите запрошенные права. После возврата включите connector в нужном чате. В организационном аккаунте добавление может требовать настроек владельца. [Инструкция Claude](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

Claude обнаруживает AS через metadata, регистрируется, использует PKCE S256 и resource `/mcp`, затем предъявляет access token. Пользовательский API-ключ для этого сценария не нужен. Общее описание процесса и допустимые callback URLs: [OAuth](/docs/oauth).

**ChatGPT**

В интерфейсе, где доступно добавление собственного MCP server, выберите Add custom MCP server (например, Plugins → `+`), задайте URL `https://aos.edgelab.space/mcp`, OAuth и **DCR**. Пройдите вход и согласие AgentOS, затем включите полученное подключение. Имена пунктов зависят от версии и настроек workspace; наличие этой возможности в конкретном аккаунте код AgentOS не определяет. [Официальная инструкция OpenAI](https://developers.openai.com/plugins/build/app-quickstart).

Сервер AgentOS допускает оба вида callback ChatGPT из своего allowlist и возвращает `iss` на authorize callback. Выбирайте регистрацию public client с `token_endpoint_auth_method=none`; `client_secret` не задаётся. [OAuth-требования OpenAI](https://developers.openai.com/plugins/build/auth).

Эти шаги описывают предусмотренную кодом интеграцию. Локальные тесты проверяют протокол с SDK и fake-клиентами; успешное подключение конкретного аккаунта Claude.ai/ChatGPT на production ими не подтверждается.

**Claude Code: API-ключ в заголовке**

В кабинете откройте страницу API-ключей, создайте ключ с `course:read`; для анкеты и плана добавьте `profile:read`; для истории тьютора отдельно включите `tutor:read`; для отметок уроков и шагов плана – `progress:write`. Секрет показывается один раз. Пример команды:

```bash
claude mcp add --scope user --transport http agentos https://aos.edgelab.space/mcp \
  --header 'Authorization: Bearer aos_live_...'
```

Откройте `/mcp` в Claude Code и проверьте подключение. `aos_live_...` здесь и далее – **маска**, её нужно заменить выданным ключом. Настоящий формат ключа – `aos3.sk_` и 43 base64url-символа. CLI сохраняет конфигурацию подключения; обращайтесь с ней как с секретом. [Синтаксис Claude Code](https://code.claude.com/docs/en/mcp).

**Codex**

Для персонального ключа добавьте в свой `config.toml` (пользовательская конфигурация Codex или доверенная конфигурация проекта):

```toml
[mcp_servers.agentos]
url = "https://aos.edgelab.space/mcp"
bearer_token_env_var = "AOS_API_KEY"
```

Перед запуском Codex задайте `AOS_API_KEY` выданным ключом в окружении своего терминала; в примерах это `aos_live_...`. Проверка списка: `codex mcp list`, в TUI – `/mcp`. Принцип настройки и поддержка Streamable HTTP подтверждены [официальной документацией OpenAI](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

Вариант с OAuth:

```bash
codex mcp add agentos --url https://aos.edgelab.space/mcp
codex mcp login agentos
```

Используйте его вместо bearer-конфигурации того же подключения. Если клиент предлагает выбор регистрации, выбирайте DCR; в версиях с соответствующим флагом: `codex mcp login agentos --oauth-client-registration dcr`. Callback должен быть разрешённым локальным HTTP URL; remote HTTPS callback AgentOS allowlist не принимает. [OAuth и регистрация в Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

## Как проходит подключение

```mermaid
sequenceDiagram
  actor Student as Студент
  participant Client as MCP-клиент
  participant AS as AgentOS OAuth
  participant MCP as AgentOS MCP
  Client->>MCP: POST /mcp без токена
  MCP-->>Client: 401 + resource_metadata
  Client->>AS: Discovery и DCR
  Client->>AS: Authorize + PKCE S256 + resource
  AS->>Student: Email-код или другой вход, затем согласие
  Student->>AS: Разрешить доступ
  AS-->>Client: code + state + iss
  Client->>AS: Обмен code + code_verifier
  AS-->>Client: Access token; refresh при зарегистрированном refresh grant
  Client->>MCP: Initialize, tools/list, tools/call с bearer
  MCP-->>Client: Результат в рамках прав студента
```

Без сессии OAuth показывает вход по 6-значному email-коду (10 минут, 5 попыток); pending flow хранится 30 минут. Consent показывает срок подключения: до 30 дней после использования при refresh grant, один час без него. Refresh доступен только зарегистрировавшим этот grant клиентам; сужение access scopes не сужает scopes refresh token. Metadata MCP включает `offline_access`. HTTP loopback callbacks допускают `localhost`, `127.0.0.1` и `[::1]` с любым допустимым портом и буквальным совпадением path/query; `[::1]` завершается через HTML-страницу с meta refresh и ссылкой. Подробности регистрации, email-лимитов, callback и rotation – в [OAuth](/docs/oauth).

## HTTP и формат ответа

### ALL /mcp

Фактически смонтирован ALL-обработчик: `POST` обслуживает MCP, любой другой HTTP-метод получает `405 METHOD_NOT_ALLOWED` с `Allow: POST`. Проверка Origin выполняется до проверки метода. Поведение `POST`, `GET` и `DELETE` описано ниже.

### POST /mcp

Каждый запрос требует `Authorization: Bearer aos_live_...` (API-ключ или OAuth access token); cookie кабинета и TMA не подходят. Для `initialize`, `tools/list`, `ping` отдельный scope не нужен, но проверяются token, участие и лимиты. Для `tools/call` scope зависит от инструмента. Path/query-параметров нет; тело – один JSON-RPC 2.0 объект, до **64 KiB**. Batch не поддерживается.

Обязательные HTTP headers клиента: `Content-Type: application/json`, `Accept: application/json, text/event-stream`. После initialize отправляйте согласованную версию в `MCP-Protocol-Version`. Необязательный `Origin`, если передан, должен быть точно `https://aos.edgelab.space`. На каждый HTTP-запрос создаётся новый server: `Mcp-Session-Id` нет, SSE-подписок нет. Для новых версий SDK использует JSON; для старых клиентов может вернуть один конечный результат через SSE.

```bash
curl -sS https://aos.edgelab.space/mcp \
  -H 'Authorization: Bearer aos_live_...' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"example-client","version":"1.0"}}}'

curl -sS https://aos.edgelab.space/mcp \
  -H 'Authorization: Bearer aos_live_...' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-03-26' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
```

`initialize` возвращает результат MCP handshake: согласованную версию, server capabilities и `serverInfo` (`name: agentos`, `title: AgentOS`, `version: 1.0.0`, icons). `tools/list` возвращает `result.tools[]` с именем, описанием, `inputSchema`, `outputSchema`, annotations. `tools/call`:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"completed\":[],\"positions\":{},\"homework\":{},\"milestonesDone\":[]}"
      }
    ],
    "structuredContent": {
      "completed": [],
      "positions": {},
      "homework": {},
      "milestonesDone": []
    }
  }
}
```

`structuredContent` – тот же JSON, что соответствующий REST-метод, за исключением ограниченного `aos_whoami`. Ошибка внутри инструмента: `result.isError=true`, `content[0].text` содержит JSON REST envelope `{error:{code,message,retryAfterSec?,issues?}}`; это может прийти с HTTP 200. Недостаточный scope возвращается здесь же: `result.isError=true`, `error.code=INSUFFICIENT_SCOPE` в JSON из `content[0].text`, обычно с HTTP 200. Некорректные аргументы может отклонить SDK до вызова capability.

HTTP-ошибки: `401 UNAUTHENTICATED` с discovery challenge; `403 CREDENTIAL_NOT_ALLOWED`, `ORIGIN_REJECTED`, `NO_ENTITLEMENT` (до инструмента); `429 RATE_LIMITED`; `503 ENTITLEMENT_UNAVAILABLE`; `500 INTERNAL`. MCP body cap – HTTP `413`, JSON-RPC `-32000`; invalid JSON – HTTP `400`, `-32700`; batch – HTTP `400`, `-32600`; `subscriptions/listen` – HTTP `200`, `-32601`. SDK также может отказать с `400`, `406`, `415` при нарушении протокола/headers. Подробности: [ошибки](/docs/errors).

Лимиты общие с REST для конкретного ключа: **60/min**, **2000/UTC day**; на студента **3000/UTC day**; `aos_search` и `aos_get_transcript` дополнительно **20/min/key**. Вызов существующего инструмента сверх лимита после распознавания ключа получает `isError` с `RATE_LIMITED` и `retryAfterSec`; остальные запросы получают HTTP 429. Ответы персональные: `Cache-Control: private, no-store`, `Vary: Authorization`.

### GET /mcp

Поток GET не поддерживается: HTTP **405** REST envelope с `METHOD_NOT_ALLOWED`, `Allow: POST`. Auth/scope не проверяются, отдельного лимита нет, body/query/path нет. При чужом Origin проверка выполняется раньше и даёт 403. Пример:

```bash
curl -i https://aos.edgelab.space/mcp
```

### DELETE /mcp

Сессии MCP отсутствуют, удалять нечего: HTTP **405** REST envelope с `METHOD_NOT_ALLOWED`, `Allow: POST`. Auth/scope не проверяются, отдельного лимита нет, body/query/path нет. Чужой Origin даёт 403 раньше проверки метода. Другие методы также отклоняются. Пример:

```bash
curl -i -X DELETE https://aos.edgelab.space/mcp
```
