Skip to main content
Esta página cobre os problemas mais comuns ao conectar um cliente MCP (Claude Code, Cursor, Microsoft Copilot) ao MCP Server da strattum.ai. Para cada um, você tem o sintoma, a causa mais provável e a correção. O MCP Server expõe três ferramentas — search_entity, get_entity_context e search_knowledge — e roteia as chamadas para a Memory API (porta 8002) e a Knowledge API (porta 8003). A maioria das falhas está numa dessas três camadas: subprocesso, autenticação ou APIs internas.

​
Problemas comuns

Sintoma: o servidor strattum não sobe, ou o cliente MCP acusa erro ao iniciar o subprocesso.Causa provável:
  • No modo stdio (Claude Code, Cursor), o Python 3.12+ não está no PATH ou o pacote não está instalado.
  • O cwd / PYTHONPATH da configuração não aponta para o diretório src/ do MCP Server.
Correção:
  • Valide o ambiente: python --version e python -m mcp_server.server --help. Se o segundo falhar, reinstale com pip install -e . a partir de services/mcp-server.
  • Confirme que cwd e PYTHONPATH apontam para .../strattum-ai/services/mcp-server/src, onde o módulo mcp_server vive.
  • Verifique que MCP_TRANSPORT=stdio está no bloco env da configuração do cliente.
Sintoma: o servidor sobe, mas as chamadas retornam erro de conexão às APIs internas.Causa provável: o ambiente local não está em execução, ou as URLs configuradas não batem com onde as APIs estão ouvindo.Correção:
  • Confirme que Memory API e Knowledge API respondem:
Ambos devem retornar 200 OK. Se não, suba o ambiente com docker compose up -d em strattum-deploy/starter.
  • Confira MEMORY_API_URL (http://localhost:8002) e KNOWLEDGE_API_URL (http://localhost:8003) na configuração.
  • Se as APIs demoram a responder, ajuste HTTP_TIMEOUT (padrão 30 segundos).
Sintoma: no modo SSE (Microsoft Copilot, agentes remotos), o cliente recebe erro de autenticação ao chamar o servidor na porta 8005.Causa provável: o MCP_API_KEY do servidor e o bearer token do cliente não coincidem. Se MCP_API_KEY estiver vazio, a autenticação fica desabilitada e um token enviado pelo cliente é ignorado. [verificar mensagem de erro exata]Correção:
  • Defina o mesmo MCP_API_KEY no servidor e configure o cliente com esse bearer token.
  • Confirme MCP_HOST (0.0.0.0) e MCP_PORT (8005) e que a porta 8005 está acessível ao cliente remoto.
  • Para uso local via stdio, autenticação por token não se aplica — use MCP_TRANSPORT=stdio.
Sintoma: o cliente conecta, mas search_entity, get_entity_context e search_knowledge não aparecem entre as ferramentas disponíveis.Causa provável: o servidor strattum não foi carregado da configuração — arquivo errado, JSON inválido ou caminho incorreto.Correção:
  • No Claude Code, confira o bloco mcpServers em ~/.claude.json (global) ou .claude/settings.json (por projeto). O JSON precisa ser válido.
  • Reinicie o cliente após editar a configuração e peça “Liste as ferramentas MCP disponíveis” — a resposta deve incluir as três.
  • Se ainda não aparecem, valide o subprocesso pela accordion “O cliente não conecta ao MCP Server” acima.

​
Onde ver os logs

Ajuste LOG_LEVEL=DEBUG no env do MCP Server para detalhar o roteamento das chamadas às APIs internas. Os healthchecks curl http://localhost:8002/healthz e curl http://localhost:8003/healthz isolam se o problema está no servidor MCP ou nas APIs por trás dele.

​
Como abrir um chamado

Se o servidor sobe, as APIs respondem 200 OK e as ferramentas ainda falham, abra um chamado no canal #strattum-suporte no Slack. Inclua o cliente MCP usado, o transporte (stdio ou sse), o trecho relevante da configuração (sem segredos) e a saída com LOG_LEVEL=DEBUG.

​
Próximos passos

MCP Server — visão geral

Ferramentas expostas, transportes e variáveis de ambiente.

Configuração pós-instalação

Onde o MCP Server entra na sequência de setup da plataforma.

Problemas no Memory

Quando search_entity conecta mas a entidade não existe no grafo.

Knowledge sem resultados

Quando search_knowledge conecta mas a busca volta vazia.