MCP
MCP-сервер AgentOS
Адрес – https:, транспорт – Streamable HTTP без сессий: каждый запрос – один JSON-RPC 2.0 объект, ответ – JSON. Авторизация – OAuth access token или персональный API-ключ в Authorization:; cookie кабинета и токен Mini App не подходят. Отдельных MCP resources и prompts нет – только инструменты.
| Параметр | Значение |
|---|---|
| URL | https: |
| Имя сервера | agentos (serverInfo.: AgentOS) |
| Транспорт | Streamable HTTP, только POST |
| Авторизация | OAuth (authorization code + PKCE S256, DCR) или API-ключ aos3. |
| Инструменты | Список и права |
Пошаговое подключение с готовыми командами – в Быстром старте.
Подключение за 1 минуту#
Claude.ai
Откройте Connectors → Add custom connector (в новых версиях интерфейса Customize → Connectors), задайте имя AgentOS и URL https:. Выберите OAuth-вход и автоматическую регистрацию клиента (Register automatically / DCR): AgentOS не поддерживает published identity / CIMD. Нажмите Connect, войдите по коду из почты в открывшейся вкладке (или выберите другой способ входа) и разрешите запрошенные права. После возврата включите connector в нужном чате. В организационном аккаунте добавление может требовать настроек владельца. Инструкция Claude.
Claude обнаруживает AS через metadata, регистрируется, использует PKCE S256 и resource /, затем предъявляет access token. Пользовательский API-ключ для этого сценария не нужен. Общее описание процесса и допустимые callback URLs: OAuth.
ChatGPT
В интерфейсе, где доступно добавление собственного MCP server, выберите Add custom MCP server (например, Plugins → +), задайте URL https:, OAuth и DCR. Пройдите вход и согласие AgentOS, затем включите полученное подключение. Имена пунктов зависят от версии и настроек workspace; наличие этой возможности в конкретном аккаунте код AgentOS не определяет. Официальная инструкция OpenAI.
Сервер AgentOS допускает оба вида callback ChatGPT из своего allowlist и возвращает iss на authorize callback. Выбирайте регистрацию public client с token_; client_ не задаётся. OAuth-требования OpenAI.
Эти шаги описывают предусмотренную кодом интеграцию. Локальные тесты проверяют протокол с SDK и fake-клиентами; успешное подключение конкретного аккаунта Claude.ai/ChatGPT на production ими не подтверждается.
Claude Code: API-ключ в заголовке
В кабинете откройте страницу API-ключей, создайте ключ с course:; для анкеты и плана добавьте profile:; для истории тьютора отдельно включите tutor:; для отметок уроков и шагов плана – progress:. Секрет показывается один раз. Пример команды:
claude mcp add --scope user --transport http agentos https://aos.edgelab.space/mcp \
--header 'Authorization: Bearer aos_live_...'Откройте / в Claude Code и проверьте подключение. aos_ здесь и далее – маска, её нужно заменить выданным ключом. Настоящий формат ключа – aos3. и 43 base64url-символа. CLI сохраняет конфигурацию подключения; обращайтесь с ней как с секретом. Синтаксис Claude Code.
Codex
Для персонального ключа добавьте в свой config. (пользовательская конфигурация Codex или доверенная конфигурация проекта):
[mcp_servers.agentos]
url = "https://aos.edgelab.space/mcp"
bearer_token_env_var = "AOS_API_KEY"Перед запуском Codex задайте AOS_ выданным ключом в окружении своего терминала; в примерах это aos_. Проверка списка: codex , в TUI – /. Принцип настройки и поддержка Streamable HTTP подтверждены официальной документацией OpenAI.
Вариант с OAuth:
codex mcp add agentos --url https://aos.edgelab.space/mcp
codex mcp login agentosИспользуйте его вместо bearer-конфигурации того же подключения. Если клиент предлагает выбор регистрации, выбирайте DCR; в версиях с соответствующим флагом: codex . Callback должен быть разрешённым локальным HTTP URL; remote HTTPS callback AgentOS allowlist не принимает. OAuth и регистрация в Codex.
Как проходит подключение#
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_. HTTP loopback callbacks допускают localhost, 127. и [ с любым допустимым портом и буквальным совпадением path/query; [ завершается через HTML-страницу с meta refresh и ссылкой. Подробности регистрации, email-лимитов, callback и rotation – в OAuth.
HTTP и формат ответа#
ALL /mcp#
Фактически смонтирован ALL-обработчик: POST обслуживает MCP, любой другой HTTP-метод получает 405 с Allow:. Проверка Origin выполняется до проверки метода. Поведение POST, GET и DELETE описано ниже.
POST /mcp#
Каждый запрос требует Authorization: (API-ключ или OAuth access token); cookie кабинета и TMA не подходят. Для initialize, tools/, ping отдельный scope не нужен, но проверяются token, участие и лимиты. Для tools/ scope зависит от инструмента. Path/query-параметров нет; тело – один JSON-RPC 2.0 объект, до 64 KiB. Batch не поддерживается.
Обязательные HTTP headers клиента: Content-, Accept:. После initialize отправляйте согласованную версию в MCP-. Необязательный Origin, если передан, должен быть точно https:. На каждый HTTP-запрос создаётся новый server: Mcp- нет, SSE-подписок нет. Для новых версий SDK использует JSON; для старых клиентов может вернуть один конечный результат через SSE.
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:, title:, version:, icons). tools/ возвращает result. с именем, описанием, inputSchema, outputSchema, annotations. tools/:
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{
"type": "text",
"text": "{\"completed\":[],\"positions\":{},\"homework\":{},\"milestonesDone\":[]}"
}
],
"structuredContent": {
"completed": [],
"positions": {},
"homework": {},
"milestonesDone": []
}
}
}structuredContent – тот же JSON, что соответствующий REST-метод, за исключением ограниченного aos_. Ошибка внутри инструмента: result., content[ содержит JSON REST envelope {; это может прийти с HTTP 200. Недостаточный scope возвращается здесь же: result., error. в JSON из content[, обычно с HTTP 200. Некорректные аргументы может отклонить SDK до вызова capability.
HTTP-ошибки: 401 с discovery challenge; 403 , ORIGIN_, NO_ (до инструмента); 429 ; 503 ; 500 . MCP body cap – HTTP 413, JSON-RPC -; invalid JSON – HTTP 400, -; batch – HTTP 400, -; subscriptions/ – HTTP 200, -. SDK также может отказать с 400, 406, 415 при нарушении протокола/headers. Подробности: ошибки.
Лимиты общие с REST для конкретного ключа: 60/min, 2000/UTC day; на студента 3000/UTC day; aos_ и aos_ дополнительно 20/min/key. Вызов существующего инструмента сверх лимита после распознавания ключа получает isError с RATE_ и retryAfterSec; остальные запросы получают HTTP 429. Ответы персональные: Cache-, Vary:.
GET /mcp#
Поток GET не поддерживается: HTTP 405 REST envelope с METHOD_, Allow:. Auth/scope не проверяются, отдельного лимита нет, body/query/path нет. При чужом Origin проверка выполняется раньше и даёт 403. Пример:
curl -i https://aos.edgelab.space/mcpDELETE /mcp#
Сессии MCP отсутствуют, удалять нечего: HTTP 405 REST envelope с METHOD_, Allow:. Auth/scope не проверяются, отдельного лимита нет, body/query/path нет. Чужой Origin даёт 403 раньше проверки метода. Другие методы также отклоняются. Пример:
curl -i -X DELETE https://aos.edgelab.space/mcp