MCP Servers

​

Casos de uso

• Conectar ferramentas SaaS de terceiros (Slack, Linear, Figma etc.) a agentes sem escrever integrações personalizadas.
• Expor APIs internas como ferramentas que os agentes podem chamar.
• Centralizar o gerenciamento de servidores MCP em vez de configurar conexões por ferramenta ou por agente.
• Compartilhar um único servidor MCP entre vários agentes e MCP Gateways, com controle sobre a exposição das ferramentas.

​

Como funciona

​

Schemas de ferramentas

​

Lista de MCP Servers

• Connection: a chave do servidor, com o logotipo do provedor quando o servidor vem do catálogo
• Tools: a quantidade de ferramentas da última sincronização
• Access: quais projetos podem usar o servidor
• Synced at: quando o servidor foi sincronizado pela última vez
• Created by: o membro do workspace que o adicionou

​

Configurar um MCP Server

• OpenAPI: transforma uma API REST que publica um documento OpenAPI em ferramentas. Consulte Criar a partir de uma especificação OpenAPI.
• MCP URL: conecta um servidor MCP existente pelo endpoint dele.
• Catalog: um provedor pré-configurado. Selecionar um deles preenche a URL de conexão e a autenticação esperada.

1. Preencha os detalhes gerais.
   • Key (obrigatório): letras minúsculas, dígitos, - e _, com até 64 caracteres. Serve de prefixo para os nomes das ferramentas em um MCP Gateway e define display_name. A API também exige default_tool_exposure.
   • Description (opcional): uma observação sobre o que este servidor oferece.
2. Defina a conexão.
   • Type: HTTP (padrão) ou SSE para servidores com suporte a streaming.
   • URL (obrigatório): o endpoint do servidor MCP upstream.
3. Configure a autenticação.
   • None (padrão): para servidores públicos que não exigem credenciais.
   • Static Headers: envia headers fixos em todas as requisições. Os valores dos headers são armazenados criptografados e nunca são retornados pela API. Um placeholder {{variable}} mantém um valor fora do armazenamento: o servidor armazena apenas o nome, e o valor é fornecido quando o servidor é testado, sincronizado ou quando uma ferramenta é chamada. Os valores dos placeholders não são persistidos. Para expor recursos deste servidor em um MCP Gateway, forneça os mesmos valores de variáveis em cada requisição ao gateway em params._meta["orq.ai/discoveryVariables"], indexados pelo MCP Server ID. Isso exige acesso de gerenciamento de MCP Servers em todo o workspace.
   • OAuth Client Credentials: autentica em um servidor de autorização OAuth 2.0 upstream usando o grant de client credentials. Preencha Client ID, Client secret, Token URL e, opcionalmente, Scopes. O secret é armazenado criptografado e nunca é retornado pela API. Consulte Como funciona o OAuth Client Credentials. Essa credencial é separada do fluxo OAuth que os clientes MCP usam para se conectar a um MCP Gateway.
   • Per-user OAuth: cada usuário conecta a própria conta pelo fluxo OAuth authorization code, e as chamadas de ferramentas são executadas com o token desse usuário. As configurações do cliente são opcionais e ficam em Advanced configuration. A opção aparece para conexões HTTP e SSE. Consulte OAuth por usuário.
   • Enterprise managed (ID-JAG): chama o servidor por meio de um MCP Gateway em nome de cada usuário de SSO. A opção aparece quando o plano do workspace inclui SSO e a conexão não é OpenAPI. Ative o Cross App Access antes de depender dela: sem ele, o formulário avisa que as chamadas de ferramentas falham até que um administrador o habilite. Consulte Autorização gerenciada pela empresa.
4. Teste a conexão. Clique em Test connection para verificar o servidor antes de salvar. Para Enterprise managed (ID-JAG), isso verifica a descoberta de autorização sem solicitar um token de usuário nem listar ferramentas. Os outros tipos de autenticação validam a conexão e retornam as ferramentas descobertas.
5. Clique em Create.

​

Como funciona o OAuth Client Credentials

• Quando Test connection é executado.
• Quando o servidor sincroniza suas ferramentas.
• Quando uma ferramenta é executada por um Agent ou um MCP Gateway.

​

OAuth por usuário

• Pela página de detalhes do servidor: clique em Connect account e conclua o login no servidor upstream. A página passa a mostrar Connected e sincroniza as ferramentas do servidor. Quando uma conexão armazenada para de funcionar, o botão passa a exibir Reconnect account.
• Por um Agent: um servidor por usuário anexado e sem conexão mostra Connect account na configuração do Agent. Uma execução de Agent que chega ao servidor sem conexão falha com Connect your account to this MCP server before using it.
• Por um MCP Gateway: quando o usuário que faz a chamada não tem conexão, o gateway pede ao cliente MCP que abra um link de conexão (Connect your account for <server>). Clientes sem suporte a URL elicitation recebem o link em um erro de ferramenta. O link abre uma página Connect account que lista o servidor, o recurso, o cliente e os scopes. Clique em Continue para autorizar ou em Decline para interromper a operação pendente e, em seguida, repita a requisição pelo cliente. Requisições sem identidade de usuário falham com This server requires a signed-in user connection.

​

Autorização gerenciada pela empresa

​

Solucionar problemas da autorização gerenciada pela empresa

​

Criar a partir de uma especificação OpenAPI

1. Selecione Create na aba MCP Servers e, em seguida, Create no card OpenAPI.
2. Em Specification, escolha uma Source:
   • URL: o endereço do documento. Sync o busca novamente para obter as alterações.
   • Paste or upload: um documento JSON ou YAML. O documento não é armazenado, então alterar as ferramentas depois exige carregar o documento novamente em Settings.
3. Clique em Load operations e selecione as operações a expor. As operações que não podem se tornar ferramentas são listadas em Skipped operations, com o motivo.
4. Verifique a Base URL: as requisições são enviadas para ela. Ela é preenchida a partir da primeira entrada de servers do documento.
5. Configure a Authentication com None, Static Headers (por exemplo, um header de chave de API ou Authorization: Bearer {{token}}) ou OAuth Client Credentials.
6. Clique em Create. As ferramentas ficam disponíveis imediatamente; não há nada para sincronizar.

• OpenAPI 3.0, 3.1 e 3.2. Documentos Swagger 2.0 são rejeitados.
• Apenas corpos de requisição JSON.
• No máximo 300 ferramentas por servidor e um documento de 10 MB.
• $ref para outros arquivos ou URLs não é seguido; as operações que usam um são ignoradas.
• A autenticação Enterprise managed não está disponível.
• As exportações para IDEs chegam aos servidores OpenAPI apenas por meio de um MCP Gateway.

curl -X POST https://router.toqan.ai/eu/v2/mcp-servers \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "petstore",
    "display_name": "petstore",
    "connection": {
      "type": "MCP_CONNECTION_TYPE_OPENAPI",
      "url": "https://petstore3.swagger.io/api/v3"
    },
    "auth": { "type": "MCP_AUTH_TYPE_NONE" },
    "default_tool_exposure": { "mode": "MCP_TOOL_EXPOSURE_MODE_ALL" },
    "openapi": {
      "document_url": "https://petstore3.swagger.io/api/v3/openapi.json",
      "operations": ["getPetById", "findPetsByStatus"]
    }
  }'

​

Após a criação

• Veja as ferramentas descobertas em Explorer → Tools. Selecione uma ferramenta à esquerda para inspecionar sua descrição, argumentos e schema à direita. Use Filters para encontrar ferramentas Read only, Destructive, Idempotent ou Open world.
• Inspecione o conteúdo dos recursos em Explorer → Resources. Selecione um recurso para ler seu conteúdo atual. Para um template, informe os parâmetros e selecione Read resource. Use Refresh para lê-lo novamente. Para um MCP App, inspecione o HTML em Source e abra uma ferramenta relacionada para ver as entradas que ela aceita.
• Controle a exposição das ferramentas quando o servidor estiver vinculado a um MCP Gateway: marque as caixas de seleção das ferramentas na aba MCP Servers do gateway (consulte MCP Gateways). A exposição também aceita um filtro read-only na API. Ele mantém apenas as ferramentas que o servidor upstream anota como somente leitura (readOnlyHint). O gateway confia nessa anotação e não verifica o que a ferramenta faz.
• Teste uma ferramenta preenchendo os argumentos e clicando em Run tool. O teste invoca a ferramenta no servidor upstream e mostra a resposta.
• Selecione Sync em Explorer para atualizar o catálogo do servidor. As ferramentas recém-descobertas aparecem em Tools, e as ferramentas descobertas anteriormente que estão ausentes são marcadas como MISSING.
• Abra o menu da linha para Sync, Edit ou Delete. O menu de detalhes também oferece Share, para copiar o link da página, e Duplicate, para reutilizar a conexão e as configurações de ferramentas com uma nova chave.
• Configure o acesso por projeto na aba Settings. Em Access control, escolha All projects para compartilhar o servidor com todo o workspace, ou Custom e defina cada projeto como Enabled ou Disabled. Um MCP Gateway só pode vincular servidores cujo acesso por projeto o inclua.

​

Excluir um servidor

curl -X PATCH https://router.toqan.ai/eu/v2/mcp-gateways/<gateway-id> \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_links": [
      {
        "mcp_server_id": "mcp_server_01JQ0K5R8N2ZC7X4M9T3V6HWBE",
        "alias": "weather",
        "tool_exposure": { "mode": "MCP_TOOL_EXPOSURE_MODE_ALL" }
      }
    ]
  }'

curl -X DELETE https://router.toqan.ai/eu/v2/mcp-servers/<server-id> \
  -H "Authorization: Bearer $TOQAN_API_KEY"

​

Monitorar o uso

​

Anexar a um Gateway