> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # MCP Gateway > Agrupe vários servidores MCP por trás de um único endpoint de MCP Gateway, com uma superfície de ferramentas unificada, aliases e controles de acesso a ferramentas por equipe. Consulte [URLs e autenticação HTTP](/docs/pt-BR/reference/base-urls.md) e a referência da API para os formatos completos de solicitação e resposta. Crie um único endpoint MCP voltado aos clientes que agrupa um ou mais **MCP Servers**. Os clientes se conectam à URL do MCP Gateway e obtêm uma superfície de ferramentas unificada sem precisar conhecer as URLs individuais dos servidores nem os detalhes de autenticação. O gateway funciona como um **servidor MCP virtual**: ele agrega ferramentas de vários servidores upstream por trás de um único endereço. > [!NOTE] > > Esta página aborda os **MCP Gateways**, endpoints voltados aos clientes que agrupam os **MCP Servers** upstream aos quais o Toqan Router se conecta. Trata-se de uma funcionalidade diferente do servidor MCP do próprio Toqan Router, ao qual os assistentes de programação se conectam para administrar o workspace. O **MCP Portal** é a área do **AI Gateway** que gerencia **MCP Gateways** e **MCP Servers**. Abra-o em **AI Gateway > MCP Portal** na barra lateral; a aba **MCP Gateways** lista todos os gateways do workspace, com uma linha por gateway: * **Name**: a chave do gateway * **Servers**: os **MCP Servers** vinculados, como uma pilha de avatares de servidores, com uma contagem `+N` quando a lista é longa * **Exposed tools**: quantas ferramentas o gateway expõe aos clientes * **Access**: quais projetos podem usar o gateway * **Public URL**: o endpoint ao qual os clientes se conectam, com um controle para copiar ## Como funciona Um **servidor MCP virtual** é um único endpoint que dá aos clientes acesso a ferramentas de vários **MCP Servers** upstream. O gateway agrega esses servidores por trás de um único endereço, cuida da autenticação e do roteamento e resolve internamente os conflitos de nomes de ferramentas. Os clientes se conectam a uma única URL e veem todas as ferramentas vinculadas como se viessem de um único provedor. ## Casos de uso * Expor vários servidores MCP por meio de um único endpoint para clientes que não conseguem gerenciar várias conexões. * Criar aliases para as ferramentas dos servidores com nomes consistentes, para que os clientes não quebrem quando os nomes das ferramentas upstream mudarem. * Governar o acesso a ferramentas por equipe: os administradores montam um MCP Gateway a partir de um subconjunto selecionado de ferramentas de vários **MCP Servers**, para que as equipes de Marketing e de Pesquisa possam compartilhar os mesmos servidores acessando ferramentas diferentes. ## Configurar um MCP Gateway > [tab] AI Studio > > Clique em MCP Gateway. > > **General** > > * **Description** (opcional): uma observação sobre o que este MCP Gateway oferece. > * **Key** (obrigatório): letras minúsculas, dígitos, `-` e `_`, com até 64 caracteres. Compõe a URL do MCP Gateway e não pode ser alterada após a criação. > > **Tools** > > * **Tool exposure mode**: como o MCP Gateway apresenta as ferramentas aos clientes conectados. **Code mode** (padrão) expõe uma única ferramenta fornecida pelo MCP Gateway que cuida da descoberta e da execução internamente. **Direct** expõe cada ferramenta upstream individualmente. > * **Tool naming**: como os nomes das ferramentas recebem namespace entre os servidores. **Always prefix with server key** (padrão) adiciona a todas as ferramentas o prefixo da chave do servidor, ou do alias dele, se houver um definido por vínculo. **Prefix only on collision** adiciona prefixo apenas aos nomes conflitantes. > > **Runtime limits** > > * Cada limite listado em [Limites de execução](#runtime-limits), preenchido com seu valor padrão. > > Clique em Create. > [tab] API e SDK > > Tanto `key` quanto `display_name` são obrigatórios. O console não tem um campo de nome de exibição e define `display_name` como a chave. > > ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} > curl -X POST https://router.toqan.ai/eu/v2/mcp-gateways \ > -H "Authorization: Bearer $TOQAN_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{ > "key": "support-tools", > "display_name": "Support tools", > "mode": "MCP_GATEWAY_MODE_CODE", > "tool_naming": "MCP_TOOL_NAMING_PREFIX_WITH_SERVER_KEY" > }' > ``` > > `mode` e `tool_naming` espelham as configurações de ferramentas do formulário: > > * **Tool exposure mode**: `MCP_GATEWAY_MODE_CODE` (**Code mode**, o padrão) ou `MCP_GATEWAY_MODE_DIRECT` (**Direct**). > > * **Tool naming**: `MCP_TOOL_NAMING_PREFIX_WITH_SERVER_KEY` (**Always prefix with server key**) ou `MCP_TOOL_NAMING_PREFIX_ON_COLLISION` (**Prefix only on collision**, o padrão da API). > > > [!TIP] > > > > Consulte a [referência completa da API para criar um MCP gateway](/docs/pt-BR/reference/mcp-gateway/create-an-mcp-gateway.md). ## Após a criação O **Toqan Router** redireciona para a aba **MCP Servers** do novo MCP Gateway. Clique em + Add server para vincular qualquer servidor já configurado em [MCP Servers](/docs/pt-BR/ai-gateway/mcp-portal/mcp-servers.md). Apenas servidores que concluíram a sincronização inicial podem ser vinculados. Pela API, [PATCH /v2/mcp-gateways/{id}](/docs/pt-BR/reference/mcp-gateway/update-an-mcp-gateway.md) com `server_links` substitui os servidores vinculados. Um array `server_links` vazio não altera nada; envie `clear_server_links: true` para desvincular todos os servidores. Os dois campos não podem ser combinados. > [!NOTE] > > Vincule apenas **MCP Servers** cujo acesso por projeto inclua o acesso por projeto do **MCP Gateway**. Um **MCP Gateway** em **All projects**, portanto, precisa de **MCP Servers** em **All projects**; altere o escopo de um servidor na aba **Settings** dele, conforme descrito em [MCP Servers](/docs/pt-BR/ai-gateway/mcp-portal/mcp-servers.md#after-creation). A página de detalhes do MCP Gateway tem quatro abas: * **Overview**: o tráfego do MCP Gateway e a seção **Connect**, com o comando que os clientes usam para acessá-lo. * **MCP Servers**: os servidores vinculados e as ferramentas que cada um expõe. * Filtre com **Search servers and tools...**. Cada linha mostra `N / M` ferramentas expostas; expanda-a para ver a lista de ferramentas, **Select all** e o contador `N of M tools exposed`. * As caixas de seleção são aplicadas imediatamente. Cada ferramenta tem um selo **Open world**, **Read only**, **Idempotent** ou **Destructive**. * O painel lateral mostra **Traffic**, o prefixo **Alias** e os detalhes de **Connection**. * **Clients**: os clientes MCP autorizados por [OAuth](#oauth), com a opção de revogar o acesso deles. * **Settings**: a descrição do MCP Gateway, as configurações de ferramentas, [plugins e limites de execução](#security-settings) e o [acesso por projeto](#project-access), editáveis após a criação. Menu da linha: **View details**, **Edit**, **Delete**. Menu adicional dos detalhes: **Edit**, **Share**, **Delete**, em que **Share** copia um link para a página. ## Funções e permissões As funções do workspace definem quem pode visualizar e gerenciar o MCP Portal. As permissões de MCP seguem a função e não são configuráveis por equipe nem por gateway. | Ação | Admin | Developer | Researcher | | - | :-: | :-: | :-: | | Visualizar MCP Gateways e MCP Servers | ✓ | ✓ | ✓ | | Visualizar clientes autorizados | ✓ | ✓ | ✓ | | Criar e editar MCP Servers | ✓ | ✓ | | | Excluir MCP Servers | ✓ | | | | Criar, editar e excluir MCP Gateways | ✓ | | | | Vincular servidores e escolher quais ferramentas um gateway expõe | ✓ | | | | Definir compartilhamento, plugins e limites de execução do gateway | ✓ | | | | Revogar um cliente autorizado | ✓ | | | A autorização de um cliente é self-service: a pessoa que faz login a aprova no navegador e fica com o token resultante. Revogar um cliente autorizado exige **Admin**. As permissões das funções se aplicam a pessoas. As [chaves de API](/docs/pt-BR/ai-gateway/configuration/api-keys.md) são autorizadas separadamente, pelo acesso concedido à própria chave. ## Acesso por projeto > [tab] AI Studio > > Um MCP Gateway fica visível para os projetos que podem usá-lo. A coluna **Access** da lista de gateways mostra o escopo atual: **All Projects**, **No projects** ou os nomes dos projetos compartilhados. Um novo gateway é compartilhado com todos os projetos. > > Altere o escopo na aba **Settings**. Em **Access control**, escolha **All projects** para compartilhar o gateway com todo o workspace, ou **Custom** e defina cada projeto como **Enabled** ou **Disabled**. > [tab] API e SDK > > O bloco `sharing` na criação ou na atualização substitui o escopo. Envie `all_projects` para compartilhar o gateway com todos os projetos, ou `selected.project_ids` para listar os projetos que podem usá-lo. Um projeto **Disabled** deixa de acessar o gateway. > > ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} > curl -X PATCH https://router.toqan.ai/eu/v2/mcp-gateways/ \ > -H "Authorization: Bearer $TOQAN_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{ > "sharing": { > "selected": { "project_ids": ["proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V"] } > } > }' > ``` > > Envie `all_projects` em vez de `selected` para compartilhar o gateway com todos os projetos. > [!NOTE] > > O escopo de projeto define quais projetos podem acessar o gateway. Uma chave de API acessa os gateways dos projetos aos quais está delimitada; uma chave gerada para uma sessão de Agent também acessa apenas os gateways anexados a esse Agent. ## Excluir um gateway > [tab] AI Studio > > Exclua um gateway pelo item **Delete** no menu da linha da lista de gateways, pelo item **Delete** no menu adicional da página de detalhes ou pelo botão Delete gateway na aba **Settings**. Cada um pede confirmação. > [tab] API e SDK > > ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} > curl -X DELETE https://router.toqan.ai/eu/v2/mcp-gateways/ \ > -H "Authorization: Bearer $TOQAN_API_KEY" > ``` > > > [!TIP] > > > > Consulte a [referência completa da API para excluir um MCP gateway](/docs/pt-BR/reference/mcp-gateway/delete-an-mcp-gateway.md). ## Configurações de segurança A aba **Settings** contém os plugins, os **Guardrails** e os limites de execução que controlam o que o MCP Gateway encaminha e quanto ele encaminha. Os mesmos campos de limites de execução aparecem no formulário **Create MCP Gateway**. ### Plugins Os plugins anexados a um MCP Gateway são executados em todas as chamadas de ferramentas que ele atende. As [Guardrail Rules](/docs/pt-BR/ai-gateway/configuration/guardrail-rules.md) não são executadas em chamadas de ferramentas. Para verificar o tráfego de ferramentas, use plugins e os próprios [Guardrails](#guardrails) do gateway. Clique em Add Plugin para anexar um. Cada plugin listado tem um ícone para configurá-lo e um ícone para removê-lo. | Plugin | Comportamento no MCP Gateway | | - | - | | **PII Redaction** | Substitui informações de identificação pessoal nos argumentos de texto livre das ferramentas por placeholders antes que a chamada chegue ao **MCP Server** upstream e, depois, restaura os valores originais no resultado da ferramenta. Argumentos cujo schema fixa o valor (`enum`, `const`, `pattern`, `format`) são encaminhados sem alterações. Configure as entidades a mascarar, o limite de detecção e o comportamento em caso de falha. Consulte [PII Redaction](/docs/pt-BR/ai-gateway/features/plugins/pii-redaction.md). | | **Trace Scrubbing** | Mascara os campos selecionados (`system`, `input`, `output`, `metadata`, `variables` ou `all`) nos traces que o MCP Gateway armazena para cada chamada de ferramenta. Consulte [Trace Scrubbing](/docs/pt-BR/ai-gateway/features/plugins/trace-scrubbing.md). | > [!NOTE] > > Os plugins impostos no nível do workspace funcionam como um mínimo: um MCP Gateway pode adicionar plugins ou tornar suas configurações mais rígidas, mas não pode remover nem enfraquecer um plugin imposto. ### Guardrails Os **Guardrails** anexados a um MCP Gateway verificam as chamadas de ferramentas que ele atende. Em **Guardrails**, clique em **Add** para escolher um **Evaluator** e defina onde ele é executado: * **Input**: verifica o nome e os argumentos da ferramenta antes que a chamada chegue ao **MCP Server** upstream. As leituras de recursos também são verificadas nesta etapa. * **Output**: verifica o resultado da ferramenta antes que ele retorne ao cliente. * **Both**: é executado nas duas etapas. Um **Evaluator** marcado como **Guardrail** é executado em todas as chamadas e bloqueia a chamada quando a verificação falha. Qualquer outro **Evaluator** é executado na sua taxa de amostragem e apenas registra uma pontuação. Os **Guardrails** são executados depois da [PII Redaction](/docs/pt-BR/ai-gateway/features/plugins/pii-redaction.md), então um juiz nunca vê os valores mascarados. ### Limites de execução Limites aplicados ao tráfego que passa pelo MCP Gateway. Defina-os no formulário **Create MCP Gateway** ou na aba **Settings** de um gateway existente: todos os limites são configurados apenas no console, e nenhum campo da API ou método do SDK os define. Cada campo aceita um número inteiro a partir de `0`. | Limite | Padrão | O que limita | | - | - | - | | **Request timeout (ms)** | `30000` | Uma requisição do gateway a um **MCP Server** upstream. `0` recorre a um timeout interno de 10 minutos. | | **Tool timeout (ms)** | `30000` | Uma `tools/call`, incluindo a conexão com o servidor upstream. `0` remove o prazo por chamada. | | **Max request bytes** | `1048576` | O corpo da requisição JSON-RPC que o gateway aceita. `0` remove o limite. | | **Max response bytes** | `1048576` | Uma resposta de um servidor upstream e cada resultado de `tools/list`. `0` remove o limite. | | **Max tools / gateway** | `100` | As ferramentas expostas em todos os servidores vinculados. Ferramentas excedentes são removidas do catálogo sem erro, e `0` deixa o catálogo sem limite. Um gateway criado pela API armazena `0`, então não tem limite de ferramentas até que um seja definido no console. | | **Per-token req/min** | `60` | Requisições por minuto de um token de acesso. `0` desativa a verificação. | | **Per-gateway req/min** | `1000` | Requisições por minuto do gateway como um todo. `0` desativa a verificação. | Atingir um limite de requisição, de resposta, de timeout ou de taxa, ou perder o servidor upstream, faz a chamada ser respondida com um erro que o cliente MCP exibe. Três deles também alteram o status HTTP; os demais chegam como uma resposta `200` contendo o erro. | Situação | Status HTTP | O que o cliente exibe | | - | - | - | | Corpo da requisição acima de **Max request bytes** | `413` | `request body exceeds maximum allowed size` | | Taxa por token ou por gateway excedida | `429` | `rate limit exceeded` | | Armazenamento de limite de taxa inacessível | `503` | `rate limit check unavailable` | | Resultado de `tools/list` acima de **Max response bytes** | `200` | `response exceeds maximum allowed size` | | Resposta upstream acima de **Max response bytes** | `200` | `upstream response exceeds maximum allowed size` | | Timeout durante `tools/call` | `200` | `upstream tool call timed out` | | Timeout em outra requisição upstream | `200` | `upstream request timed out` | | Host upstream inacessível | `200` | `upstream connection refused` ou `upstream host not found` | | O upstream rejeita as credenciais | `200` | `upstream authentication failed`, `upstream access denied` ou `upstream resource not found` | | O upstream falha de qualquer outra forma | `200` | `upstream request failed` | Uma ferramenta que é executada e relata a própria falha não é um erro: o gateway retorna um resultado normal de `tools/call` com `isError: true` e o conteúdo upstream. ## Delimitar ferramentas Um gateway expõe uma única superfície de ferramentas a todos os projetos com os quais é compartilhado. Quais ferramentas um chamador acessa depende então da exposição do gateway e daquilo a que o chamador está vinculado. | Camada | O que controla | Onde definir | | - | - | - | | **Exposição de ferramentas do gateway** | Quais ferramentas o gateway disponibiliza, de cada **MCP Server** vinculado. | Aba **MCP Servers**, caixas de seleção das ferramentas. | | **Acesso por projeto** | Se um projeto acessa ou não o gateway. | Aba **Settings**, **Access control**. Consulte [Acesso por projeto](#project-access). | | **Chave de API** | Se a chave pode chamar o gateway, por domínio de permissão, e quais projetos ela acessa. Uma chave gerada para uma sessão de Agent fica vinculada aos gateways desse Agent. `mcp_access` limita a chave aos gateways em `allowed_mcp_gateway_ids` ou bloqueia todos os gateways com `deny_all`. | Consulte [Chaves de API](/docs/pt-BR/ai-gateway/configuration/api-keys.md). Defina `mcp_access` pela [API](/docs/pt-BR/reference/api-keys/update-an-api-key.md); o formulário de chave de API não tem um campo para isso. | Um projeto acessa toda a superfície de ferramentas exposta ou nenhuma parte dela. Logins pelo navegador e chaves não vinculadas a uma sessão de Agent acessam toda a superfície exposta. ### Dar a uma equipe suas próprias ferramentas Duas equipes que acessam o mesmo gateway veem as mesmas ferramentas, então dê a uma equipe suas próprias ferramentas com um gateway exclusivo: crie um **MCP Gateway** para o projeto da equipe, exponha apenas as ferramentas que a equipe pode chamar e compartilhe-o apenas com esse projeto. Os outros projetos não conseguem acessá-lo. Atribua projetos a equipes em **Settings → Organization → Teams**. Consulte Membros e equipes. ### Delimitação de ferramentas por usuário Não é possível delimitar ferramentas a um usuário individual. Ferramentas individuais não podem ser concedidas nem negadas a um usuário específico. O acesso segue a exposição do gateway e os projetos que o chamador acessa. Um token [OAuth](#oauth) acessa um **MCP Gateway** como um todo, e não ferramentas individuais, e seus scopes definem quais métodos ele pode chamar: `mcp:tools` abrange ferramentas, e `mcp:resources` abrange recursos e skills. Uma chamada fora dos scopes do token retorna `403` com um desafio `insufficient_scope` que indica o scope ausente. Para [servidores gerenciados pela empresa](/docs/pt-BR/ai-gateway/mcp-portal/mcp-servers.md#enterprise-managed-authorization), o provedor de identidade também decide se o usuário pode acessar o aplicativo upstream. Uma ferramenta pode aparecer no catálogo do gateway mesmo quando esse provedor nega a chamada do usuário. ## Conectar um cliente Qualquer cliente compatível com MCP pode acessar o MCP Gateway, na maioria das vezes um agente de programação como Claude Code, Cursor ou Codex. Consulte Agentes de programação para ver a lista completa. **Versões do protocolo** | Par | Revisões | Transporte | | - | - | - | | Cliente MCP para o gateway | `2026-07-28`, `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05` | Streamable HTTP: `POST https://router.toqan.ai/eu/v3/mcp/`, a opção `--transport http` nos exemplos abaixo | | Gateway para o **MCP Server** upstream | Negociada com cada servidor a partir do mesmo conjunto | O tipo de conexão do servidor, **HTTP** ou **SSE**. **STDIO** é rejeitado. | **Extensões** O gateway anuncia estas extensões na capability `extensions` de `initialize` e `server/discover`: | Extensão | Anunciada quando | | - | - | | `io.modelcontextprotocol/skills` | O gateway expõe skills | | `io.modelcontextprotocol/oauth-client-credentials` | Sempre. Consulte [Client credentials](#client-credentials) | | `io.modelcontextprotocol/enterprise-managed-authorization` | Sempre. Consulte [Autorização gerenciada pela empresa](#enterprise-managed-authorization) | Um cliente que não envia nenhuma revisão, ou que envia uma mais antiga que as da lista, é atendido com `2024-11-05`: `initialize` responde com essa revisão, e o gateway responde às notificações com `200` em vez do `202` exigido pelo Streamable HTTP. Uma revisão mais recente que a mais nova suportada retorna `UnsupportedProtocolVersion`, com as revisões aceitas em `supported`. > [!NOTE] > > Os exemplos abaixo usam `https://router.toqan.ai/eu` como host padrão. Para São Paulo, use `https://router.toqan.ai/br`. O campo `public_url` da API retorna o endpoint de conexão completo (que pode ser relativo quando nenhuma URL base pública está configurada). Os clientes se autenticam de uma destas formas: * [**OAuth**](#oauth) (padrão): login pelo navegador. Use para clientes interativos. * [**Client credentials**](#client-credentials): um cliente pré-registrado obtém tokens de curta duração sem a presença de um usuário. Use para serviços e automações. * [**Autorização gerenciada pela empresa**](#enterprise-managed-authorization): o provedor de identidade da empresa emite um ID-JAG que o cliente troca por um token, sem tela de consentimento. * [**Chave de API**](#api-key): um token bearer na configuração do cliente. Use para clientes headless que não conseguem executar um fluxo OAuth. Ao chamar um [servidor gerenciado pela empresa](/docs/pt-BR/ai-gateway/mcp-portal/mcp-servers.md#enterprise-managed-authorization), use o OAuth do gateway ou uma chave de API pertencente a um usuário cujo dono tenha feito login por SSO. Chaves de contas de serviço e chaves geradas por federação não conseguem fornecer a identidade de usuário necessária. Faça login novamente depois que um administrador habilitar o Cross App Access ou quando uma chamada retornar `ENTERPRISE_AUTH_REAUTH_REQUIRED`. ### OAuth O OAuth é o padrão. O cliente faz login pelo navegador e recebe um token delimitado a este MCP Gateway e à pessoa que fez login, então nenhuma chave de API do workspace fica armazenada na configuração do cliente. > [!NOTE] > > Este fluxo autentica clientes MCP no MCP Gateway. As credenciais que o gateway usa para acessar cada **MCP Server** upstream são configuradas no próprio servidor. Consulte [MCP Servers](/docs/pt-BR/ai-gateway/mcp-portal/mcp-servers.md#set-up-an-mcp-server). **1. Configure o cliente** A seção **Connect** na aba **Overview** mostra a chave do gateway e este comando. Copie-o de lá ou execute-o substituindo ``: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx add-mcp https://router.toqan.ai/eu/v3/mcp/ --name ``` Registre o MCP Gateway diretamente no cliente, substituindo `` pela chave do gateway da seção **Connect**: > [tab] Claude Code > > ```bash wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} > claude mcp add --transport http https://router.toqan.ai/eu/v3/mcp/ > ``` > > O Claude Code abre o navegador para aprovação no primeiro uso. Confirme com `claude mcp list`. > [tab] Cursor > > Adicione o MCP Gateway em **Cursor Settings → Tools & MCP → New MCP Server** e cole: > > ```json wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "mcpServers": { > "": { > "url": "https://router.toqan.ai/eu/v3/mcp/" > } > } > } > ``` > > Salve a configuração e conclua a aprovação no navegador quando o Cursor solicitar. > [tab] Codex > > ```bash wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} > codex mcp add --url https://router.toqan.ai/eu/v3/mcp/ > ``` > > Execute `codex mcp login ` para concluir a aprovação no navegador. > [tab] VS Code > > Adicione o MCP Gateway com o comando **MCP: Add Server**, selecione **HTTP (HTTP or Server-Sent Events)** e insira `https://router.toqan.ai/eu/v3/mcp/` como URL do servidor. O VS Code grava um `.vscode/mcp.json`: > > ```json wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "servers": { > "": { > "url": "https://router.toqan.ai/eu/v3/mcp/", > "type": "http" > } > } > } > ``` > > O VS Code abre o navegador para aprovação na primeira conexão. **2. Aprove o acesso** No primeiro uso, o cliente abre o navegador. A página de aprovação indica o cliente e o MCP Gateway ao qual ele está solicitando acesso. Clique em Approve para emitir o token ou em Deny para rejeitar a solicitação. **Gerenciar clientes autorizados** Todo cliente autorizado aparece na aba **Clients** com o nome do cliente, quando ele se autenticou e quem o criou. Escolha **Revoke access** no menu de um cliente para impedir que ele renove seu token; o token de acesso que ele já possui continua válido até expirar, em até 30 minutos. **Como o login funciona** O MCP Gateway implementa a especificação de autorização do MCP sobre o OAuth 2.0: * **Descoberta**: uma requisição não autenticada ao gateway retorna `401` com um header `WWW-Authenticate` que aponta para os documentos de metadados do gateway. O documento de recurso protegido em `/.well-known/oauth-protected-resource/v3/mcp/` indica o servidor de autorização; o documento do servidor de autorização em `/.well-known/oauth-authorization-server/v2/auth/mcp`, que atende todos os gateways, lista seus endpoints. * **Registro dinâmico de clientes**: o cliente se registra no endpoint de registro do servidor de autorização, então nenhum client ID ou secret precisa ser provisionado com antecedência. * **Authorization code com PKCE**: o login usa o fluxo authorization code com Proof Key for Code Exchange (PKCE) e o método de desafio `S256`, que vincula o código de autorização ao cliente que o solicitou. O token carrega os scopes que o cliente solicitou, `mcp:tools` e `mcp:resources` por padrão, apenas neste MCP Gateway. Um cliente registrado com o grant `refresh_token` o renova sem um novo login até que o acesso seja revogado; qualquer outro cliente faz login novamente quando o token expira. Cada renovação substitui o refresh token; apresentar um token substituído mais de 60 segundos depois revoga o acesso do cliente, e a pessoa precisa fazer login novamente. **Metadados do servidor de autorização** `/.well-known/oauth-authorization-server/v2/auth/mcp` anuncia: | Campo | Valores | | - | - | | `grant_types_supported` | `authorization_code`, `refresh_token`, `client_credentials`, `urn:ietf:params:oauth:grant-type:jwt-bearer` | | `token_endpoint_auth_methods_supported` | `client_secret_basic`, `client_secret_post`, `private_key_jwt`, `none` | | `token_endpoint_auth_signing_alg_values_supported` | `RS256`, `PS256`, `ES256` | | `client_id_metadata_document_supported` | `true` | | `authorization_grant_profiles_supported` | `urn:ietf:params:oauth:grant-profile:id-jag` | | `jwks_uri` | `/jwks.json`, as chaves que assinam os tokens de acesso de client credentials e ID-JAG | ### Client credentials Um cliente pré-registrado se autentica como ele mesmo e recebe um token de acesso de 10 minutos vinculado a um MCP Gateway, sem navegador e sem refresh token. O cliente é seu próprio principal e tem as mesmas configurações de acesso de uma chave de API: projeto e permissões. **1. Registre o cliente** Em **Settings → API Keys → OAuth Clients**, clique em **+ Client**. Escolha o grant **Client credentials**, o acesso (projeto e permissões) e como o cliente se autentica: * **Client secret (Basic)** ou **Client secret (POST)**: o secret é exibido uma única vez após a criação. Use **Rotate secret** para substituí-lo. * **Private key JWT**: cole um JSON Web Key Set ou uma URL de JWKS com as chaves públicas. O cliente assina asserções RFC 7523 com `RS256`, `PS256` ou `ES256`. Apenas Admins do workspace e chaves de gerenciamento podem registrar, editar ou excluir clientes. As permissões precisam incluir a execução de MCP Gateway, que os novos clientes têm por padrão. Cada cliente tem uma chave de API gerenciada por trás, exibida como **Managed** na página **API Keys**; ela não pode ser usada, editada nem excluída lá. Desabilitar ou excluir o cliente a revoga. A aba **Clients** de um gateway lista os clientes OAuth que podem acessá-lo. **2. Solicite um token** Envie a URL do gateway como o `resource` da RFC 8707: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST https://router.toqan.ai/eu/v2/auth/mcp/token \ -u "$CLIENT_ID:$CLIENT_SECRET" \ -d grant_type=client_credentials \ -d resource=https://router.toqan.ai/eu/v3/mcp/ \ -d "scope=mcp:tools mcp:resources" ``` A resposta contém `access_token`, `token_type`, `expires_in` e o `scope` concedido. Envie o token como `Authorization: Bearer ` e solicite um novo antes que ele expire. Com o SDK de MCP para TypeScript, os providers executam a descoberta e a requisição de token: > [tab] Client secret > > ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}} > import { Client } from '@modelcontextprotocol/sdk/client/index.js'; > import { ClientCredentialsProvider } from '@modelcontextprotocol/sdk/client/auth-extensions.js'; > import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'; > > const authProvider = new ClientCredentialsProvider({ > clientId: process.env.TOQAN_MCP_CLIENT_ID!, > clientSecret: process.env.TOQAN_MCP_CLIENT_SECRET!, > expectedIssuer: 'https://router.toqan.ai/eu/v2/auth/mcp', > }); > > const transport = new StreamableHTTPClientTransport( > new URL('https://router.toqan.ai/eu/v3/mcp/'), > { authProvider }, > ); > const client = new Client({ name: 'nightly-sync', version: '1.0.0' }); > await client.connect(transport); > ``` > [tab] Private key JWT > > ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}} > import { PrivateKeyJwtProvider } from '@modelcontextprotocol/sdk/client/auth-extensions.js'; > > const authProvider = new PrivateKeyJwtProvider({ > clientId: process.env.TOQAN_MCP_CLIENT_ID!, > privateKey: process.env.TOQAN_MCP_CLIENT_PRIVATE_KEY!, > algorithm: 'RS256', > expectedIssuer: 'https://router.toqan.ai/eu/v2/auth/mcp', > }); > ``` > > Passe `authProvider` para `StreamableHTTPClientTransport` como no exemplo com client secret. > [tab] Python > > ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} > import httpx > > response = httpx.post( > "https://router.toqan.ai/eu/v2/auth/mcp/token", > auth=(CLIENT_ID, CLIENT_SECRET), > data={ > "grant_type": "client_credentials", > "resource": "https://router.toqan.ai/eu/v3/mcp/", > "scope": "mcp:tools mcp:resources", > }, > ) > access_token = response.json()["access_token"] > ``` > > Envie `access_token` como token bearer a partir de qualquer cliente MCP. Prefira client credentials a uma [chave de API](#api-key) quando a credencial precisar ter curta duração, usar uma chave privada em vez de um secret compartilhado ou ter seu acesso gerenciado junto com o cliente, em vez de com uma chave de longa duração. ### Autorização gerenciada pela empresa O provedor de identidade da empresa decide quais usuários podem usar quais clientes MCP. Um cliente conectado por SSO solicita ao provedor de identidade um Identity Assertion JWT Authorization Grant (ID-JAG) e o troca no **Toqan Router** por um token do gateway, então o usuário nunca vê a página de aprovação. **1. Conecte o provedor de identidade** Configure primeiro a conexão SSO: Configurar SSO. **2. Confie no provedor de identidade** Em **Settings → SSO**, abra a conexão SSO e habilite **ID-JAG trust**. Liste os clientes autorizados a resgatar ID-JAGs: client IDs pré-registrados ou URLs de Client ID Metadata Document. Opcionalmente, limite os scopes. Conexões OIDC confiam apenas no issuer do SSO; conexões SAML precisam da URL do issuer que o provedor de identidade coloca em seus ID-JAGs. **3. Configure o provedor de identidade** Registre o cliente MCP no provedor de identidade e permita a troca de tokens para o **Toqan Router**. O ID-JAG deve usar: * `aud`: o issuer do servidor de autorização, `https://router.toqan.ai/eu/v2/auth/mcp`. * `resource`: a URL do gateway, `https://router.toqan.ai/eu/v3/mcp/`, ou omita-o e envie `resource` na requisição de token. * `client_id`: o ID do cliente no **Toqan Router**. **4. Troque o ID-JAG** ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST https://router.toqan.ai/eu/v2/auth/mcp/token \ -u "$CLIENT_ID:$CLIENT_SECRET" \ -d grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \ -d assertion=$ID_JAG \ -d resource=https://router.toqan.ai/eu/v3/mcp/ ``` O token de 15 minutos age como o usuário vinculado, com as funções e o acesso por projeto desse usuário. Apenas um cliente pré-registrado com acesso total pode acessar o servidor MCP da plataforma. Não há refresh token: solicite um novo ID-JAG quando ele expirar. **Vinculação de contas** O **Toqan Router** vincula o `sub` do ID-JAG a uma conta na primeira vez que o vê e reutiliza esse vínculo depois. No primeiro uso, o ID-JAG precisa conter `email_verified: true` e um `email` em um dos domínios permitidos da conexão SSO que corresponda a uma conta já existente no workspace. O **Toqan Router** nunca cria contas nem associações a partir de um ID-JAG; uma requisição sem membro correspondente é rejeitada com `invalid_grant`. Alterar o issuer da conexão apaga seus vínculos. Cada ID-JAG é aceito uma única vez, deve ter validade de 10 minutos ou menos e é verificado em relação às chaves publicadas pelo provedor de identidade. ### Chave de API Passe uma chave de API como token bearer em vez de fazer login. Defina `TOQAN_API_KEY` e registre o MCP Gateway: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx add-mcp https://router.toqan.ai/eu/v3/mcp/ \ --name \ --header "Authorization: Bearer $TOQAN_API_KEY" ``` > [tab] Claude Code > > ```bash wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} > claude mcp add --transport http https://router.toqan.ai/eu/v3/mcp/ --header "Authorization: Bearer ${TOQAN_API_KEY}" > ``` > > Defina `TOQAN_API_KEY` antes de executar o comando. Confirme com `claude mcp list`. > [tab] Cursor > > ```json wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "mcpServers": { > "": { > "url": "https://router.toqan.ai/eu/v3/mcp/", > "headers": { > "Authorization": "Bearer YOUR_TOQAN_API_KEY" > } > } > } > } > ``` > > Substitua `YOUR_TOQAN_API_KEY` por uma chave de API. Salve a configuração; o servidor se conecta e exibe um indicador verde. > [tab] Codex > > ```bash wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} > codex mcp add --url https://router.toqan.ai/eu/v3/mcp/ --bearer-token-env-var TOQAN_API_KEY > ``` > > Exporte `TOQAN_API_KEY` no shell que inicia o Codex. > [tab] VS Code > > ```json wrap theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "inputs": [ > { > "type": "promptString", > "id": "toqan-api-key", > "description": "Toqan Router API Key", > "password": true > } > ], > "servers": { > "": { > "url": "https://router.toqan.ai/eu/v3/mcp/", > "type": "http", > "headers": { > "Authorization": "Bearer ${input:toqan-api-key}" > } > } > } > } > ``` > > O VS Code solicita a chave de API na primeira conexão e a armazena no repositório de segredos do sistema operacional. ## Sessões Cada requisição MCP é independente. Não há uma sessão de gateway que o cliente precise inicializar, manter ativa, retomar após uma reconexão ou encerrar. ## Monitorar o uso A aba **Overview** reporta como os clientes usam o MCP Gateway. Ela abre nos últimos 7 dias, e cada card compara esse período com o anterior. Altere o período com o seletor de intervalo de tempo no canto superior direito. | Card | Descrição | | - | - | | **Tool calls** | Invocações de ferramentas roteadas pelo MCP Gateway. | | **Success** | Invocações concluídas com sucesso. | | **Errors** | Invocações que retornaram um erro. | | **P95 latency** | Duração no percentil 95 das invocações bem-sucedidas. | **Traffic and reliability** detalha ainda mais o mesmo período: * **Tool calls by outcome**: volume de chamadas ao longo do tempo, dividido entre sucessos e erros. * **Tools leaderboard**: as ferramentas mais chamadas, com a contagem de chamadas e a latência P95, listadas com seus nomes com namespace. **Performance** adiciona **Tool latency**, P50 e P95 no período, e **Calls by upstream server**, classificado por servidor. ## Auditar alterações As alterações no MCP Gateway são registradas nos Audit Logs, para que uma alteração na superfície de ferramentas exposta possa ser rastreada até quem a fez. As entradas são gravadas em dois tipos de entidade: | Tipo de entidade | Registrado quando | | - | - | | **MCP Gateway** | Um gateway é criado, atualizado ou excluído, incluindo alterações em seus servidores vinculados. | | **MCP Server** | Um servidor é criado, atualizado ou excluído. | Filtre por qualquer um dos tipos de entidade na página Audit Logs para ver apenas a atividade do MCP Portal. As entradas dos dois tipos de entidade podem ser exportadas como arquivo; consulte Exportar audit logs. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.