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

MCP

OAuth для MCP

MCP-клиенты (Claude.ai, ChatGPT, Codex и собственные агенты) получают доступ к https://aos.edgelab.space/mcp по OAuth 2.1 без client secret: public client, authorization code с PKCE S256, refresh rotation. Issuer – https://aos.edgelab.space, единственный поддержанный resource – https://aos.edgelab.space/mcp (без завершающего /). Client secret, Basic auth, implicit и client credentials не поддерживаются.

Access token – непрозрачный bearer aos3.sk_…, не JWT. Права, срок и отзыв проверяются сервером; лимиты и scopes те же, что у API-ключа.

Поток авторизации#

mermaid
sequenceDiagram
  actor Student as Студент
  participant Client as MCP-клиент
  participant AS as AgentOS OAuth
  Client->>AS: POST /oauth/register (DCR)
  AS-->>Client: client_id, без client_secret
  Client->>AS: GET /oauth/authorize + PKCE S256 + resource
  AS->>Student: Вход и форма согласия
  Student->>AS: Разрешить
  AS-->>Client: Callback: code + state + iss
  Client->>AS: POST /oauth/token (code, code_verifier)
  AS-->>Client: Access token (1 час), refresh (30 суток)
  Client->>AS: POST /oauth/token (refresh_token)
  AS-->>Client: Новая пара токенов
  1. Клиент читает discovery и регистрируется через DCR.
  2. Открывает в браузере /oauth/authorize с PKCE S256 и resource.
  3. Студент входит (кабинет или код на email) и подтверждает доступ.
  4. Клиент меняет code на токены и ходит в https://aos.edgelab.space/mcp с Authorization: Bearer ….

Discovery#

ДокументНазначение
GET /.well-known/oauth-authorization-serverМетаданные сервера авторизации: endpoints, code_challenge_methods_supported: ["S256"], token_endpoint_auth_methods_supported: ["none"], scopes
GET /.well-known/oauth-protected-resource/mcpМетаданные ресурса MCP: resource, authorization_servers, scopes

Оба документа публичные, без авторизации. Неавторизованный POST /mcp возвращает 401 и WWW-Authenticate: Bearer resource_metadata="https://aos.edgelab.space/.well-known/oauth-protected-resource/mcp"; при недействительном токене добавляется error="invalid_token".

bash
curl -sS https://aos.edgelab.space/.well-known/oauth-authorization-server
curl -sS https://aos.edgelab.space/.well-known/oauth-protected-resource/mcp

Dynamic Client Registration#

POST /oauth/register, тело application/json до 16 KiB, авторизация не нужна.

ПолеТипОбязательноЗначение
redirect_urisstring[]да1–10 URI из списка ниже
client_namestringнет1–100 символов; по умолчанию MCP client
token_endpoint_auth_methodstringнетТолько none
grant_typesstring[]нетauthorization_code и, по желанию, refresh_token; по умолчанию оба
response_typesstring[]нет["code"]
scopestringнетScopes через пробел; согласие студента всё равно обязательно
logo_uristring URLнетТолько HTTPS

Ответ 201: поля регистрации, client_id и client_id_issued_at. client_secret не выдаётся. Клиент без refresh_token в grant_types получает только access token.

bash
curl -sS https://aos.edgelab.space/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"Example client","redirect_uris":["http://localhost:8765/callback"],"token_endpoint_auth_method":"none"}'

Разрешённые redirect URIs:

  • https://claude.ai/api/mcp/auth_callback и https://claude.com/api/mcp/auth_callback;
  • https://chatgpt.com/connector_platform_oauth_redirect и https://chatgpt.com/connector/oauth/{callback_id};
  • локальные http://localhost[:port]/..., http://127.0.0.1[:port]/..., http://[::1][:port]/... – для них может меняться только порт.

HTTPS-адрес должен совпасть с зарегистрированным посимвольно. При обмене code нужен тот же redirect_uri, что был в authorize, включая порт.

Авторизация и согласие#

GET /oauth/authorize открывается в браузере студента. Без сессии кабинета показывается вход по коду из email (6 цифр, действует 10 минут) со ссылкой на другие способы входа; затем – форма согласия с именем клиента и запрошенными правами.

ПараметрОбязательноЗначение
client_idдаИз DCR
redirect_uriдаОдин из зарегистрированных
response_typeдаcode
code_challengeдаBASE64URL(SHA256(code_verifier)), 43 символа
code_challenge_methodдаS256
resourceдаhttps://aos.edgelab.space/mcp
scopeнетЧерез пробел; по умолчанию course:read profile:read
stateнетДо 2048 символов, возвращается без изменений

Нужен хотя бы один scope из course:read, profile:read, progress:write, tutor:read, mentoring:read; дополнительно можно offline_access. Пустой, неизвестный scope или один offline_access отклоняются. После решения студента браузер возвращается на callback: при согласии – code (действует 90 секунд, одноразовый), при отказе – error=access_denied; в обоих случаях state и iss. Клиент обязан проверить state и iss.

bash
curl -i -G https://aos.edgelab.space/oauth/authorize \
  --data-urlencode 'client_id=CLIENT_ID' \
  --data-urlencode 'redirect_uri=http://localhost:8765/callback' \
  --data-urlencode 'response_type=code' \
  --data-urlencode 'resource=https://aos.edgelab.space/mcp' \
  --data-urlencode 'code_challenge=PKCE_S256_CHALLENGE_43_CHARACTERS_PLACEHOLDER' \
  --data-urlencode 'code_challenge_method=S256' \
  --data-urlencode 'scope=course:read profile:read offline_access' \
  --data-urlencode 'state=CLIENT_RANDOM_STATE'

Токены#

POST /oauth/token, тело application/x-www-form-urlencoded до 16 KiB. Клиент идентифицируется client_id; заголовок Authorization и поле client_secret дают 401 invalid_client.

ПолеКогдаЗначение
grant_typeвсегдаauthorization_code или refresh_token
client_idвсегдаИз DCR
codecodeКод из callback
redirect_uricodeТочная строка из authorize
code_verifiercode43–128 символов [A-Za-z0-9._~-]
resourcecodehttps://aos.edgelab.space/mcp; при refresh можно опустить
refresh_tokenrefreshПоследний выданный refresh token
scopeнетПодмножество изначально выданных scope; шире нельзя
json
{
  "access_token": "aos3.sk_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN_PLACEHOLDER",
  "scope": "course:read profile:read offline_access"
}

Refresh token выдаётся клиентам с refresh_token в grant_types. Каждый refresh выдаёт новую пару и заново проверяет участие студента в курсе. scope в refresh сужает только новый access token; refresh token сохраняет изначально выданные права, и следующий refresh без scope (или с более широким подмножеством) может вернуть их. Шире изначально выданных scope права не становятся никогда: такой запрос получает 400 invalid_grant, а refresh token остаётся действующим. Повтор использованного code или refresh тем же клиентом отзывает подключение со всеми токенами.

bash
curl -sS https://aos.edgelab.space/oauth/token \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=CLIENT_ID' \
  --data-urlencode 'code=AUTHORIZATION_CODE_PLACEHOLDER' \
  --data-urlencode 'redirect_uri=http://localhost:8765/callback' \
  --data-urlencode 'code_verifier=CLIENT_PKCE_VERIFIER_PLACEHOLDER' \
  --data-urlencode 'resource=https://aos.edgelab.space/mcp'

curl -sS https://aos.edgelab.space/oauth/token \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'client_id=CLIENT_ID' \
  --data-urlencode 'refresh_token=LATEST_REFRESH_TOKEN_PLACEHOLDER'

Отзыв и подключения#

  • POST /oauth/revoke (form application/x-www-form-urlencoded: client_id, token) отзывает всё подключение, к которому относится токен клиента. Корректный запрос, прошедший проверки, получает 200 с пустым телом, даже если токен неизвестен или уже отозван. Неполная или повторяющая параметры форма даёт 400 invalid_request, client_secret или заголовок Authorization – 401 invalid_client. При 429 temporarily_unavailable токен не отозван: повторите тот же запрос после Retry-After.
  • Студент видит и отключает свои подключения на странице /oauth/connections (вход в кабинет обязателен).
  • Если участие в курсе закончилось, все подключения и токены студента отзываются; после восстановления нужно подключиться заново.

Сроки#

ОбъектСрок
Вход по email в рамках авторизации30 минут
Authorization code90 секунд, один раз
Access token1 час (3600 секунд)
Refresh token30 суток с каждой выдачи, одноразовый
Подключение с refreshдо 30 дней после последнего использования

Ошибки#

OAuth-ошибки приходят как JSON с полем error или как параметр error на callback.

КодКогда
invalid_requestНеверная или неполная форма, PKCE challenge, повтор параметров
invalid_redirect_uri, invalid_client_metadataDCR: redirect URI не из списка или поля не прошли проверку
invalid_scope, invalid_target, unsupported_response_typeAuthorize: неверные scope, resource или response_type
access_deniedСтудент отказал
invalid_client, unauthorized_client, unsupported_grant_typeToken: неизвестный клиент, незарегистрированный grant, неверный grant_type
invalid_grantCode или refresh истёк, использован, не совпали PKCE/redirect/scope, участие закончилось
temporarily_unavailable429 или 503: повторите после Retry-After (если заголовка нет – с экспоненциальной паузой)
server_error500, непредвиденная ошибка

Регистрация, обмен и отзыв токенов ограничены по частоте; при 429 или 503 ждите время из Retry-After. Полный справочник – Ошибки.

Scope mentoring:read#

Discovery, DCR, согласие и выдача токенов поддерживают и mentoring:read – чтение личного менторинга. Он никогда не выдаётся по умолчанию, не добавляется к существующим ключам, подключениям и refresh-токенам, а refresh не расширяет grant. Нужен тариф «Лично».