OAuth para clientes MCP · Documentação do TradeCatalog

Esta página é para pessoas que estão construindo um cliente MCP ou depurando uma conexão. Se você só quiser conectar o Claude ou o ChatGPT, veja Conectar um app de IA.

O TradeCatalog segue a especificação de autorização MCP: OAuth 2.1 com PKCE, metadados de recursos protegidos (RFC 9728) e metadados do servidor de autorização (RFC 8414).

Pontos finaisLink para esta seção#

O que	URL
Servidor MCP (recurso protegido)	`https://tradecatalog.app/mcp`
Metadados do recurso protegido	`https://tradecatalog.app/.well-known/oauth-protected-resource/mcp`
Metadados do servidor de autorização	`https://tradecatalog.app/.well-known/oauth-authorization-server`
Ponto de autorização	`https://tradecatalog.app/oauth/authorize`
Ponto de token	`https://tradecatalog.app/oauth/token`
Registro dinâmico de cliente	`https://tradecatalog.app/oauth/register`
Aplicativos conectados (para pessoas)	`https://tradecatalog.app/oauth/connections`

Os metadados do recurso protegido estão no endereço específico da rota para /mcp, conforme descrito no RFC 9728 para um recurso com uma rota. Não há nada em /.well-known/oauth-protected-resource por si só.

A conexão opcional /mcp/account adiciona uma transferência segura de cobrança exclusiva para anfitriões de agentes que permitem cobrança por assinatura de software. É um descendente do mesmo recurso protegido /mcp: use os metadados acima e resource=https://tradecatalog.app/mcp ao autorizar ou solicitar tokens. Inscrição, consentimento OAuth e acesso ao workspace usam a mesma conta. Plugins do ChatGPT conectam-se a /mcp; veja inscrição e cobrança.

EscopoLink para esta seção#

Solicite tradecatalog:read para consultas. Solicite tradecatalog:read tradecatalog:write para preparar alterações também. A página de consentimento descreve o acesso solicitado. Os direitos de leitura existentes nunca ganham acesso de gravação automaticamente. Funções e restrições de cobrança são reavaliadas ao propor e aprovar ações. Escritas consequentes exigem uma confirmação única no cartão de chat, ou na página de revisão conectada para clientes sem cartões; veja Ferramentas.

Fluxo de descobertaLink para esta seção#

O cliente chama https://tradecatalog.app/mcp sem um token.
O servidor responde com 401 Unauthorized com um cabeçalho WWW-Authenticate: Bearer apontando para os metadados do recurso protegido.
O cliente lê os metadados do recurso protegido para encontrar o servidor de autorização, https://tradecatalog.app.
O cliente lê os metadados do servidor de autorização para os endpoints acima.

bash

curl https://tradecatalog.app/.well-known/oauth-protected-resource/mcp

json

{
  "resource": "https://tradecatalog.app/mcp",
  "authorization_servers": ["https://tradecatalog.app"],
  "scopes_supported": ["tradecatalog:read", "tradecatalog:write"],
  "bearer_methods_supported": ["header"],
  "resource_name": "TradeCatalog MCP server"
}

Registrando um clienteLink para esta seção#

Use uma das seguintes opções:

Documentos de metadados de ID do cliente (recomendado): use um URL https que você controle como seu client_id, servindo os metadados do seu cliente. Pessoas aprovando a conexão veem o host desse URL como o editor.
Registro dinâmico de cliente (RFC 7591) em /oauth/register.

Qualquer pessoa pode registrar um cliente sob qualquer nome, então a página de aprovação mostra a quem a aprovação é enviada (o host de redirecionamento) e, para IDs de cliente de URL, o editor. O nome sozinho é marcado como não verificado.

AutorizaçãoLink para esta seção#

Use o fluxo de código de autorização com PKCE (S256):

Envie o navegador da pessoa para /oauth/authorize com response_type=code, client_id, redirect_uri, code_challenge, code_challenge_method=S256, state e scope=tradecatalog:read.
Se eles não estiverem conectados, o TradeCatalog pede que eles se conectem com um código por e-mail (ou Google ou Microsoft, onde habilitado), depois os retorna.
Eles veem qual app está pedindo, a conta com a qual estão conectados e o que ele pode fazer, depois escolhem Permitir ou Negar.
Permitir redireciona para seu redirect_uri com code e state. Negar redireciona com error=access_denied.
Troque o código em /oauth/token com seu code_verifier. Você recebe um token de acesso e um token de atualização.

Envie o token de acesso em cada solicitação MCP:

http

POST /mcp HTTP/1.1
Host: tradecatalog.app
Authorization: Bearer <access token>
Content-Type: application/json
Accept: application/json, text/event-stream

Tokens de acesso são de curta duração. Use o token de atualização em /oauth/token para obter um novo.

Quem pode aprovarLink para esta seção#

Qualquer usuário conectado ao TradeCatalog: funcionários de fornecedores ou compradores.
Não visitantes de demonstração (sessões de convidado). Eles são redirecionados para se conectarem corretamente.
Não há como criar uma conta por meio deste fluxo, e não há acesso somente de máquina (credenciais do cliente). Para acesso entre servidores, use a API REST com uma chave de API.

O concessão carrega apenas a identidade da pessoa. Cada chamada de ferramenta reavalia o que eles podem ver, então se eles perderem o acesso a um workspace, o app de IA também perde.

TransporteLink para esta seção#

O servidor é stateless HTTP Streamable. Ele não emite IDs de sessão; cada solicitação é independente, e ele responde com JSON em vez de um fluxo de eventos.

RevogarLink para esta seção#

As pessoas veem e desconectam aplicativos aprovados em /oauth/connections. Desconectar revoga a concessão e seus tokens imediatamente.

Também publicadoLink para esta seção#

/auth.md: um resumo curto desta página para agentes.
/.well-known/mcp/server-card.json: o cartão do servidor MCP com a lista de ferramentas.