MCP
OAuth для MCP
MCP-клиенты (Claude.ai, ChatGPT, Codex и собственные агенты) получают доступ к https: по OAuth 2.1 без client secret: public client, authorization code с PKCE S256, refresh rotation. Issuer – https:, единственный поддержанный resource – https: (без завершающего /). Client secret, Basic auth, implicit и client credentials не поддерживаются.
Access token – непрозрачный bearer aos3., не JWT. Права, срок и отзыв проверяются сервером; лимиты и scopes те же, что у API-ключа.
Поток авторизации#
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: Новая пара токенов- Клиент читает discovery и регистрируется через DCR.
- Открывает в браузере
/с PKCE S256 иoauth/ authorize resource. - Студент входит (кабинет или код на email) и подтверждает доступ.
- Клиент меняет
codeна токены и ходит вhttps:с/ / aos. edgelab. space/ mcp Authorization:.Bearer …
Discovery#
| Документ | Назначение |
|---|---|
GET | Метаданные сервера авторизации: endpoints, code_, token_, scopes |
GET | Метаданные ресурса MCP: resource, authorization_, scopes |
Оба документа публичные, без авторизации. Неавторизованный POST возвращает 401 и WWW-; при недействительном токене добавляется error=.
curl -sS https://aos.edgelab.space/.well-known/oauth-authorization-server
curl -sS https://aos.edgelab.space/.well-known/oauth-protected-resource/mcpDynamic Client Registration#
POST , тело application/ до 16 KiB, авторизация не нужна.
| Поле | Тип | Обязательно | Значение |
|---|---|---|---|
redirect_ | string[] | да | 1–10 URI из списка ниже |
client_ | string | нет | 1–100 символов; по умолчанию MCP |
token_ | string | нет | Только none |
grant_ | string[] | нет | authorization_ и, по желанию, refresh_; по умолчанию оба |
response_ | string[] | нет | [ |
scope | string | нет | Scopes через пробел; согласие студента всё равно обязательно |
logo_ | string URL | нет | Только HTTPS |
Ответ 201: поля регистрации, client_ и client_. client_ не выдаётся. Клиент без refresh_ в grant_ получает только access token.
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_, что был в authorize, включая порт.
Авторизация и согласие#
GET открывается в браузере студента. Без сессии кабинета показывается вход по коду из email (6 цифр, действует 10 минут) со ссылкой на другие способы входа; затем – форма согласия с именем клиента и запрошенными правами.
| Параметр | Обязательно | Значение |
|---|---|---|
client_ | да | Из DCR |
redirect_ | да | Один из зарегистрированных |
response_ | да | code |
code_ | да | BASE64URL(, 43 символа |
code_ | да | S256 |
resource | да | https: |
scope | нет | Через пробел; по умолчанию course: |
state | нет | До 2048 символов, возвращается без изменений |
Нужен хотя бы один scope из course:, profile:, progress:, tutor:, mentoring:; дополнительно можно offline_. Пустой, неизвестный scope или один offline_ отклоняются. После решения студента браузер возвращается на callback: при согласии – code (действует 90 секунд, одноразовый), при отказе – error=; в обоих случаях state и iss. Клиент обязан проверить state и iss.
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 , тело application/ до 16 KiB. Клиент идентифицируется client_; заголовок Authorization и поле client_ дают 401 .
| Поле | Когда | Значение |
|---|---|---|
grant_ | всегда | authorization_ или refresh_ |
client_ | всегда | Из DCR |
code | code | Код из callback |
redirect_ | code | Точная строка из authorize |
code_ | code | 43–128 символов [ |
resource | code | https:; при refresh можно опустить |
refresh_ | refresh | Последний выданный refresh token |
scope | нет | Подмножество изначально выданных scope; шире нельзя |
{
"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_ в grant_. Каждый refresh выдаёт новую пару и заново проверяет участие студента в курсе. scope в refresh сужает только новый access token; refresh token сохраняет изначально выданные права, и следующий refresh без scope (или с более широким подмножеством) может вернуть их. Шире изначально выданных scope права не становятся никогда: такой запрос получает 400 , а refresh token остаётся действующим. Повтор использованного code или refresh тем же клиентом отзывает подключение со всеми токенами.
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(form/ oauth/ revoke 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 code | 90 секунд, один раз |
| Access token | 1 час (3600 секунд) |
| Refresh token | 30 суток с каждой выдачи, одноразовый |
| Подключение с refresh | до 30 дней после последнего использования |
Ошибки#
OAuth-ошибки приходят как JSON с полем error или как параметр error на callback.
| Код | Когда |
|---|---|
invalid_ | Неверная или неполная форма, PKCE challenge, повтор параметров |
invalid_, invalid_ | DCR: redirect URI не из списка или поля не прошли проверку |
invalid_, invalid_, unsupported_ | Authorize: неверные scope, resource или response_ |
access_ | Студент отказал |
invalid_, unauthorized_, unsupported_ | Token: неизвестный клиент, незарегистрированный grant, неверный grant_ |
invalid_ | Code или refresh истёк, использован, не совпали PKCE/redirect/scope, участие закончилось |
temporarily_ | 429 или 503: повторите после Retry- (если заголовка нет – с экспоненциальной паузой) |
server_ | 500, непредвиденная ошибка |
Регистрация, обмен и отзыв токенов ограничены по частоте; при 429 или 503 ждите время из Retry-. Полный справочник – Ошибки.
Scope mentoring: read#
Discovery, DCR, согласие и выдача токенов поддерживают и mentoring: – чтение личного менторинга. Он никогда не выдаётся по умолчанию, не добавляется к существующим ключам, подключениям и refresh-токенам, а refresh не расширяет grant. Нужен тариф «Лично».