MCP Gateway — Como Funciona

Desenvolvedor

Fluxo de Conexão

Quando você conecta uma ferramenta de IA (Claude Code, Cursor, etc.) ao MCP Gateway, o seguinte acontece:

Autenticação — seu API Token é validado e sua organização, produto e role são identificados.
Carregamento de instruções — o Gateway carrega as instruções customizáveis configuradas para seu MCP Server.
Listagem de ferramentas — o Gateway retorna todas as ferramentas disponíveis (plataforma + integração).

Tipos de Ferramentas

O MCP Gateway expõe dois tipos de ferramentas:

Tipo	Origem	Disponibilidade	Exemplos
Core Tools	Nativas do Prodgy	Sempre disponíveis para todo workspace	Contexto do projeto, busca de conhecimento, execução de agentes, gestão de integrações, configurações MCP
Integration Tools	Geradas a partir das integrações instaladas	Varia por organização — depende de quais integrações estão ativas	Gestão de work items, pull requests, operações de CRM, mensageria

Core Tools dão acesso às capacidades próprias do Prodgy — base de conhecimento, agentes de IA, catálogo de integrações e configuração da plataforma. Existem independente de quais serviços externos sua organização utiliza.

Integration Tools são geradas dinamicamente a partir das integrações ativas da sua organização. Cada integração instalada (Azure DevOps, Jira, Slack, HubSpot, etc.) adiciona automaticamente suas próprias ferramentas ao Gateway. Quanto mais integrações ativas, mais ferramentas disponíveis — sem nenhuma alteração de código.

Descoberta de Ferramentas

Quando o cliente de IA solicita a lista de ferramentas disponíveis, o Gateway combina os dois tipos em uma única lista.

Para ferramentas de integração, um mecanismo de desambiguação trata conflitos:

As ferramentas são agrupadas pelo nome genérico (ex: create_work_item).
Se apenas uma integração fornece um dado nome, a ferramenta é registrada normalmente.
Se múltiplas integrações fornecem o mesmo nome, um parâmetro _integration é adicionado para que a IA possa escolher qual usar.

Execução de Ferramentas

Quando você (ou o cliente de IA) chama uma ferramenta:

Ferramentas da Plataforma

O Gateway trata a requisição e delega para a API do Prodgy. Por exemplo:

search_knowledge executa uma busca semântica na base de conhecimento do seu workspace
invoke_agent aciona um agente de IA do Prodgy com suas próprias ferramentas e system prompt

Ferramentas de Integração

O Gateway roteia a requisição para a integração apropriada:

Identifica qual integração fornece a ferramenta.
Se múltiplas integrações fornecem a mesma ferramenta e nenhum _integration foi especificado, retorna uma mensagem de desambiguação listando as opções.
Executa a ferramenta via API do Prodgy, que cuida da resolução de credenciais e da chamada HTTP para o serviço externo.

Contexto Automático de Inicialização

Na primeira chamada de ferramenta de cada sessão, o Gateway inclui automaticamente tanto o perfil do usuário (get_my_profile) quanto o contexto do workspace (get_workspace_info) junto com o resultado da ferramenta. Isso garante que o cliente de IA sempre tenha a identidade do usuário autenticado E o contexto do seu workspace (visão, OKRs, integrações ativas) sem precisar de uma chamada explícita.

Controle de Acesso

O acesso às ferramentas é determinado pelo método de autenticação e pela role do usuário:

API Tokens — acesso completo a todas as ferramentas. Restrições por role se aplicam: ferramentas que criam, atualizam ou excluem recursos da plataforma (templates de integração, configurações MCP) requerem a role SUPERADMIN ou ADMIN. As demais ferramentas estão disponíveis para qualquer usuário autenticado.
Tokens OAuth — o acesso é limitado pelos escopos concedidos durante a autorização. Cada ferramenta exige um escopo específico (mcp:read, mcp:write, mcp:execute ou mcp:admin). Chamadas sem o escopo necessário retornam erro 403 Forbidden.

Sua role é determinada pelas credenciais usadas na conexão. Usuários sem a role ou escopo necessário recebem um erro Forbidden ao chamar ferramentas restritas.

Próximos Passos

Visão Geral — modos de transporte e ferramentas disponíveis
Como Usar — configuração passo a passo para Claude Code, Cursor, Windsurf e Claude Desktop