Como conectar o OctaGym ao Claude.ai, Claude Code, Cursor ou a um script — por OAuth ou por API key.

Conectar

O servidor MCP fala Streamable HTTP numa única URL, que responde POST (JSON-RPC) e GET (eventos do servidor):

https://dashboard.octagym.ai/api/mcp/v1

Existem dois jeitos de autenticar, e a diferença entre eles importa — veja OAuth ou API key antes de escolher.

Claude.ai (recomendado, sem terminal)

Abra os conectores

No Claude.ai (navegador ou app desktop), vá em Configurações → Conectores.

Adicione um conector personalizado

Clique em Adicionar conector personalizado.

Cole a URL do servidor

Use o endereço acima (ou o que aparece em Configurações → Integrações → MCP no OctaGym) e confirme.

Autorize o acesso

Você é levado ao login do OctaGym. Escolha a empresa (ou as empresas) que essa conexão poderá acessar e clique em Autorizar.

Pronto

As ferramentas do OctaGym aparecem no Claude automaticamente — só as que o seu usuário pode usar.

Claude Code, Cursor e outros clientes

claude mcp add --transport http octagym https://dashboard.octagym.ai/api/mcp/v1

Na primeira chamada o cliente abre o fluxo OAuth no navegador: login, escolha da empresa, autorização. Nada de chave no arquivo de configuração.

{
  "mcpServers": {
    "octagym": {
      "type": "http",
      "url": "https://dashboard.octagym.ai/api/mcp/v1",
      "headers": {
        "Authorization": "Bearer SEU_TOKEN"
      }
    }
  }
}

Troque SEU_TOKEN por uma API key gerada em Configurações → Desenvolvedor (prefixo og_; chaves antigas ea_ seguem válidas).

	OAuth (usuário)	API key
Quem age	O usuário que autorizou	A empresa (service account)
Ferramentas visíveis	Só as que o cargo do usuário permite	Todas
Limite por unidade	Respeitado (usuário de uma unidade só vê a dela)	Team-wide
Múltiplas empresas	Sim, escolhidas no consentimento	Não — uma empresa por chave
Revogação	Instantânea (permissões são resolvidas a cada request)	Revogar a chave
Fila de aprovações	Funciona (a solicitação tem autor)	Ferramentas que dependem de aprovação recusam
Auditoria	Registra o usuário	Registra a conexão, sem usuário

Diferente dos escopos da API REST, uma API key usada no MCP vale como conta de serviço da empresa: ela enxerga e executa todas as ferramentas, sem o filtro de cargo. Use OAuth sempre que houver uma pessoa por trás da conexão; reserve a chave para scripts.

Algumas ferramentas exigem OAuth por construção, porque a autorização acontece no banco pelo id do usuário: get_acquirer_reconciliation, request_payment_refund e todas as que abrem solicitação no painel de aprovações.

Empresas autorizadas

No consentimento você marca uma ou mais empresas — a primeira vira a padrão. Quando a conexão tem mais de uma:

toda ferramenta ganha um parâmetro opcional team_id;
chame list_authorized_teams para descobrir os ids;
sem team_id, a ferramenta responde pedindo que você escolha a empresa;
a permissão é verificada na empresa escolhida, não na união: enxergar a ferramenta porque você é gerente na empresa A não permite executá-la na empresa B.

Conexões de uma empresa só não têm team_id e funcionam direto.

Detalhes do OAuth

Implementação OAuth 2.1 com PKCE (S256) e registro dinâmico de cliente (DCR). O servidor MCP é o próprio emissor: o token é um JWT HS256 com aud=octagym-mcp — não é um token do Supabase.

Endpoint	Papel
`/.well-known/oauth-protected-resource`	Descoberta do recurso protegido (RFC 9728)
`/.well-known/oauth-authorization-server`	Metadados do servidor de autorização
`/api/mcp/v1/oauth/register`	Registro dinâmico do cliente
`/mcp/authorize`	Tela de login e consentimento (escolha das empresas)
`/api/mcp/v1/oauth/token`	Troca do code por tokens (PKCE)

Token	Validade
Código de autorização	60 segundos
Access token	1 hora
Refresh token	90 dias

O token carrega apenas identidade e o conjunto de empresas autorizadas — nunca as permissões. Elas são resolvidas do zero a cada requisição, por isso uma mudança de cargo (ou a remoção do usuário) vale na hora, sem esperar o token expirar.

Ver e revogar conexões

Em Configurações → Integrações → MCP, o painel lateral Conectores ativos lista as conexões do seu usuário naquela empresa, com o escopo concedido, e permite revogar. Pela API:

GET  /api/mcp/clients
POST /api/mcp/clients/{id}/revoke

Revogar derruba o refresh token: o cliente precisa passar pelo consentimento de novo.

Conectar

On this page