Login com OAuth

Um assistente de IA entra no Setherion com OAuth em vez de uma chave de API: a pessoa clica em Allow em uma página do Setherion, e o assistente recebe um token. Esta página é o contrato para criar o seu próprio cliente. Se você só quer conectar Claude, ChatGPT, Cursor ou VS Code, siga MCP: conectar um assistente de IA.

O fluxo é o OAuth 2.1, como a especificação de autorização do MCP (2025-06-18) o pede:

• o fluxo de código de autorização, com PKCE (S256) sempre obrigatório;
• somente clientes públicos, sem segredo de cliente;
• registro dinâmico de clientes (RFC 7591), para que ninguém cole um client id em lugar nenhum;
• tokens vinculados a um único recurso, o endpoint do MCP (RFC 8707).

Os tokens funcionam no Servidor MCP e em nenhum outro lugar. Os endpoints REST desta referência usam uma chave de API.

1. Descubra

Envie uma solicitação ao endpoint do MCP sem nenhuma credencial. O 401 aponta para os metadados do recurso (RFC 9728) no cabeçalho WWW-Authenticate:

curl https://www.setherion.com/.well-known/oauth-protected-resource/api/mcp

{
  "resource": "https://www.setherion.com/api/mcp",
  "authorization_servers": ["https://www.setherion.com"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["mcp"],
  "resource_name": "Setherion"
}

O mesmo documento está em /.well-known/oauth-protected-resource. Depois leia os metadados do servidor de autorização (RFC 8414):

curl https://www.setherion.com/.well-known/oauth-authorization-server

{
  "issuer": "https://www.setherion.com",
  "authorization_endpoint": "https://www.setherion.com/oauth/authorize",
  "token_endpoint": "https://www.setherion.com/api/oauth/token",
  "registration_endpoint": "https://www.setherion.com/api/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["mcp"]
}

Os dois documentos, o registro e o endpoint de token respondem a qualquer origem (Access-Control-Allow-Origin: *), então um cliente em uma página do navegador pode chamá-los.

2. Registre

Registre uma vez por instalação. O registro não concede nada por si só: uma pessoa ainda precisa clicar em Allow, e o código só é enviado de volta aos endereços exatos registrados aqui.

curl -X POST https://www.setherion.com/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{ "client_name": "My assistant", "redirect_uris": ["http://localhost:8787/callback"] }'

Um endereço de redirecionamento deve ser https, ou http de volta para esta máquina (localhost, 127.0.0.1 ou [::1]). Ele não pode ter fragmento nem nome de usuário. O único endereço que não é https nem http é cursor://anysphere.cursor-mcp/oauth/callback, para apps mais antigos do Cursor.

Seja qual for o método de autenticação que um cliente peça, ele é registrado como um cliente público sem segredo, e a resposta diz isso:

{
  "client_id": "5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30",
  "client_id_issued_at": 1790000000,
  "client_name": "My assistant",
  "redirect_uris": ["http://localhost:8787/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

O status é 201. Os registros são limitados a 20 por hora por endereço de rede.

3. Pergunte à pessoa

Abra o endpoint de autorização no navegador da pessoa. É uma página, não uma API: a pessoa entra no Setherion se ainda não entrou, vê o nome que você registrou e para onde será enviada de volta, e clica em Allow ou Cancel.

https://www.setherion.com/oauth/authorize
  ?response_type=code
  &client_id=5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30
  &redirect_uri=http%3A%2F%2Flocalhost%3A8787%2Fcallback
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &state=af0ifjsldkj
  &resource=https%3A%2F%2Fwww.setherion.com%2Fapi%2Fmcp

Faça o verifier com 43 a 128 caracteres de A-Z a-z 0-9 - . _ ~ e guarde-o até o passo 4.

A pessoa é enviada de volta ao seu redirect_uri com:

• em Allow: code, state e iss (o issuer);
• em Cancel: error=access_denied, error_description=The request was declined., state e iss;
• em um problema com a solicitação, depois de o cliente e o endereço serem reconhecidos como genuínos: error, error_description, state e iss. O error é unsupported_response_type, invalid_request (PKCE ausente, ou o método não é S256) ou invalid_target (o recurso não é o endpoint do MCP).

Se o cliente é desconhecido, ou o endereço não é um dos que ele registrou, a página avisa a pessoa e não envia ninguém a lugar nenhum, então esta página nunca pode ser usada para redirecionar alguém a um endereço que você não registrou.

4. Troque o código

Envie campos codificados como formulário, como o OAuth especifica. JSON com os mesmos nomes também é aceito.

curl -X POST https://www.setherion.com/api/oauth/token \
  -d grant_type=authorization_code \
  -d code=stc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -d client_id=5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30 \
  -d redirect_uri=http://localhost:8787/callback \
  -d code_verifier=YOUR_VERIFIER

{
  "access_token": "sto_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "str_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "scope": "mcp"
}

Envie o access token ao Servidor MCP como Authorization: Bearer sto_.... Os tokens nunca ficam em cache: a resposta traz Cache-Control: no-store.

5. Renove

Um access token dura uma hora. Antes de ele acabar, ou quando o servidor MCP responder 401, troque o refresh token:

curl -X POST https://www.setherion.com/api/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=str_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -d client_id=5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30

A resposta é a mesma do passo 4, com um refresh token novo. O antigo deixa de funcionar, então guarde o novo toda vez.

Erros

Todo erro do endpoint de token tem o status 400, exceto server_error, e o corpo { "error": "...", "error_description": "..." }.

Encerrar uma conexão

A pessoa pode desconectar um assistente em Settings, depois AI assistants and MCP. Todo token dessa conexão, de acesso e de renovação, deixa de funcionar já na próxima solicitação, não quando a hora acaba. Listar e encerrar conexões só é possível a partir de uma sessão do Setherion com login feito, então nada que um assistente guarde consegue fazer isso.

Usar uma chave de API em vez disso

Um cliente que só consegue enviar um cabeçalho fixo pode pular tudo isso e enviar uma chave de API ao servidor MCP. Veja Autenticação.