К содержанию
AgentOSДокументация
  • Загружаем индекс…
llms.txtКабинет

MCP

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 нет – только инструменты.

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

Пошаговое подключение с готовыми командами – в Быстром старте.

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

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.

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

ChatGPT

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

Сервер AgentOS допускает оба вида callback ChatGPT из своего allowlist и возвращает iss на authorize callback. Выбирайте регистрацию public client с token_endpoint_auth_method=none; client_secret не задаётся. OAuth-требования OpenAI.

Эти шаги описывают предусмотренную кодом интеграцию. Локальные тесты проверяют протокол с 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.

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.

Вариант с 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.

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

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.

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. Подробности: ошибки.

Лимиты общие с 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