Integração MCP (acesso para ferramentas de IA)¶

O Turbo EA inclui um servidor MCP (Model Context Protocol) integrado que permite que ferramentas de IA — como Claude Desktop, GitHub Copilot, Cursor e VS Code — consultem seus dados de EA diretamente. Os usuários se autenticam através do provedor SSO existente, e cada consulta respeita suas permissões individuais.

Este recurso é opcional e não inicia automaticamente. Requer que o SSO esteja configurado, que o perfil MCP esteja ativado no Docker Compose e que um administrador o ative na interface de configurações.

Como funciona¶

Ferramenta de IA (Claude, Copilot, etc.)
    │
    │  Protocolo MCP (HTTP + SSE)
    ▼
Servidor MCP do Turbo EA (:8001, interno)
    │
    │  OAuth 2.1 com PKCE
    │  delega ao provedor SSO
    ▼
Backend do Turbo EA (:8000)
    │
    │  RBAC por usuário
    ▼
PostgreSQL

Um usuário adiciona a URL do servidor MCP à sua ferramenta de IA.
Na primeira conexão, a ferramenta abre uma janela do navegador para autenticação SSO.
Após o login, o servidor MCP emite seu próprio token de acesso (respaldado pelo JWT do Turbo EA do usuário).
A ferramenta de IA usa este token para todas as solicitações subsequentes. Os tokens se renovam automaticamente.
Cada consulta passa pelo sistema de permissões normal do Turbo EA — os usuários só veem os dados aos quais têm acesso.

Pré-requisitos¶

Antes de habilitar o MCP, você deve ter:

SSO configurado e funcionando — O MCP delega a autenticação ao seu provedor SSO (Microsoft Entra ID, Google Workspace, Okta ou OIDC genérico). Consulte o guia de Autenticação e SSO.
HTTPS com um domínio público — O fluxo OAuth requer uma URI de redirecionamento estável. Implante atrás de um proxy reverso com terminação TLS (Caddy, Traefik, Cloudflare Tunnel, etc.).

Configuração¶

Passo 1: Iniciar o serviço MCP¶

O servidor MCP é um perfil opcional do Docker Compose. Adicione --profile mcp ao seu comando de inicialização:

docker compose --profile mcp up --build -d

Isso inicia um container Python leve (porta 8001, apenas interno) junto ao backend e frontend. O Nginx redireciona automaticamente as solicitações /mcp/ para ele.

Passo 2: Configurar variáveis de ambiente¶

Adicione estas ao seu arquivo .env:

TURBO_EA_PUBLIC_URL=https://seu-dominio.exemplo.com
MCP_PUBLIC_URL=https://seu-dominio.exemplo.com/mcp

Variável	Padrão	Descrição
`TURBO_EA_PUBLIC_URL`	`http://localhost:8920`	A URL pública da sua instância Turbo EA
`MCP_PUBLIC_URL`	`http://localhost:8920/mcp`	A URL pública do servidor MCP (usada nas URIs de redirecionamento OAuth)
`MCP_PORT`	`8001`	Porta interna do container MCP (raramente precisa de alteração)

Passo 3: Adicionar a URI de redirecionamento OAuth ao seu aplicativo SSO¶

No registro de aplicativo do seu provedor SSO (o mesmo que você configurou para o login do Turbo EA), adicione esta URI de redirecionamento:

https://seu-dominio.exemplo.com/mcp/oauth/callback

Isso é necessário para o fluxo OAuth que autentica os usuários quando se conectam a partir da ferramenta de IA.

Passo 4: Habilitar MCP nas configurações de administração¶

Vá para Configurações na área de administração e selecione a aba AI.
Role até a seção Integração MCP (Acesso a ferramentas de IA).
Ative o interruptor para habilitar o MCP.
A interface mostrará a URL do servidor MCP e instruções de configuração para compartilhar com sua equipe.

Warning

O interruptor fica desabilitado se o SSO não estiver configurado. Configure o SSO primeiro.

Conectar ferramentas de IA¶

Uma vez habilitado o MCP, compartilhe a URL do servidor MCP com sua equipe. Cada usuário a adiciona à sua ferramenta de IA:

Claude Desktop¶

Abra Configurações > Conectores > Adicionar conector personalizado.
Insira a URL do servidor MCP: https://seu-dominio.exemplo.com/mcp
Clique em Conectar — uma janela do navegador abre para o login SSO.
Após a autenticação, o Claude pode consultar seus dados de EA.

VS Code (GitHub Copilot / Cursor)¶

Adicione ao .vscode/mcp.json do seu workspace:

{
  "servers": {
    "turbo-ea": {
      "type": "http",
      "url": "https://seu-dominio.exemplo.com/mcp/mcp"
    }
  }
}

O duplo /mcp/mcp é intencional — o primeiro /mcp/ é o caminho do proxy Nginx, o segundo é o endpoint do protocolo MCP.

Teste local (modo stdio)¶

Para desenvolvimento local ou testes sem SSO/HTTPS, você pode executar o servidor MCP em modo stdio — o Claude Desktop o inicia diretamente como processo local.

1. Instalar o pacote do servidor MCP:

pip install ./mcp-server

2. Adicionar à configuração do Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "turbo-ea": {
      "command": "python",
      "args": ["-m", "turbo_ea_mcp", "--stdio"],
      "env": {
        "TURBO_EA_URL": "http://localhost:8000",
        "TURBO_EA_EMAIL": "seu@email.com",
        "TURBO_EA_PASSWORD": "sua-senha"
      }
    }
  }
}

Neste modo, o servidor se autentica com email/senha e renova o token automaticamente em segundo plano.

Capacidades disponíveis¶

O servidor MCP fornece acesso somente leitura aos dados de EA. Ele não pode criar, modificar ou excluir nada.

Ferramentas¶

Ferramenta	Descrição
`search_cards`	Pesquisar e filtrar cards por tipo, status ou texto livre
`get_card`	Obter detalhes completos de um card por UUID
`get_card_relations`	Obter todas as relações conectadas a um card
`get_card_hierarchy`	Obter ancestrais e filhos de um card
`list_card_types`	Listar todos os tipos de card no metamodelo
`get_relation_types`	Listar tipos de relação, opcionalmente filtrados por tipo de card
`get_dashboard`	Obter dados do painel de KPIs (contagens, qualidade de dados, aprovações)
`get_landscape`	Obter cards agrupados por um tipo relacionado

Recursos¶

URI	Descrição
`turbo-ea://types`	Todos os tipos de card no metamodelo
`turbo-ea://relation-types`	Todos os tipos de relação
`turbo-ea://dashboard`	KPIs do painel e estatísticas resumidas

Prompts guiados¶

Prompt	Descrição
`analyze_landscape`	Análise em várias etapas: visão geral do painel, tipos, relações
`find_card`	Pesquisar um card por nome, obter detalhes e relações
`explore_dependencies`	Mapear as dependências de um card

Permissões¶

Papel	Acesso
Administrador	Configurar ajustes MCP (permissão `admin.mcp`)
Todos os usuários autenticados	Consultar dados de EA através do servidor MCP (respeita suas permissões existentes no nível de card e aplicação)

A permissão admin.mcp controla quem pode gerenciar as configurações de MCP. Está disponível apenas para o papel de Administrador por padrão. Papéis personalizados podem receber esta permissão através da página de administração de Papéis.

O acesso a dados através do MCP segue o mesmo modelo RBAC da interface web — não há permissões de dados específicas do MCP.

Segurança¶

Autenticação delegada por SSO: Os usuários se autenticam através do provedor SSO corporativo. O servidor MCP nunca vê ou armazena senhas.
OAuth 2.1 com PKCE: O fluxo de autenticação utiliza Proof Key for Code Exchange (S256) para prevenir a interceptação de códigos de autorização.
RBAC por usuário: Cada consulta MCP é executada com as permissões do usuário autenticado. Sem contas de serviço compartilhadas.
Acesso somente leitura: O servidor MCP só pode ler dados. Não pode criar, atualizar ou excluir cards, relações ou quaisquer outros recursos.
Rotação de tokens: Tokens de acesso expiram após 1 hora. Tokens de renovação duram 30 dias. Códigos de autorização são de uso único e expiram após 10 minutos.
Porta apenas interna: O container MCP expõe a porta 8001 apenas na rede Docker interna. Todo acesso externo passa pelo proxy reverso Nginx.

Solução de problemas¶

Problema	Solução
O interruptor MCP está desabilitado nas configurações	O SSO deve ser configurado primeiro. Vá para Configurações > aba Autenticação e configure um provedor SSO.
«host not found» nos logs do Nginx	O serviço MCP não está em execução. Inicie-o com `docker compose --profile mcp up -d`. A configuração do Nginx lida com isso de forma elegante (resposta 502, sem queda).
O callback OAuth falha	Verifique se adicionou `https://seu-dominio.exemplo.com/mcp/oauth/callback` como URI de redirecionamento no registro do aplicativo SSO.
A ferramenta de IA não consegue conectar	Verifique se `MCP_PUBLIC_URL` corresponde à URL acessível a partir da máquina do usuário. Certifique-se de que o HTTPS está funcionando.
O usuário obtém resultados vazios	O MCP respeita as permissões RBAC. Se um usuário tem acesso restrito, verá apenas os cards que seu papel permite.
A conexão cai após 1 hora	A ferramenta de IA deveria lidar com a renovação de tokens automaticamente. Caso contrário, reconecte.