> ## Documentation Index
> Fetch the complete documentation index at: https://strattumai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP não conecta

> Diagnóstico dos problemas mais comuns do MCP Server: cliente que não conecta, falha de autenticação e ferramentas que não aparecem na lista.

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

<AccordionGroup>
  <Accordion title="O cliente não conecta ao MCP Server" icon="plug-circle-xmark">
    **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.
  </Accordion>

  <Accordion title="Erro 'Could not reach the Memory API'" icon="server">
    **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:

    ```bash theme={null}
    curl http://localhost:8002/healthz
    curl http://localhost:8003/healthz
    ```

    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).
  </Accordion>

  <Accordion title="Falha de autenticação no modo SSE" icon="key">
    **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`.
  </Accordion>

  <Accordion title="As ferramentas MCP não aparecem na lista" icon="wrench">
    **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.
  </Accordion>
</AccordionGroup>

***

## 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

<CardGroup cols={2}>
  <Card title="MCP Server — visão geral" icon="plug" href="/mcp-server/index">
    Ferramentas expostas, transportes e variáveis de ambiente.
  </Card>

  <Card title="Configuração pós-instalação" icon="gear" href="/getting-started/configuration">
    Onde o MCP Server entra na sequência de setup da plataforma.
  </Card>

  <Card title="Problemas no Memory" icon="brain" href="/troubleshooting/memory">
    Quando `search_entity` conecta mas a entidade não existe no grafo.
  </Card>

  <Card title="Knowledge sem resultados" icon="book-open" href="/troubleshooting/knowledge">
    Quando `search_knowledge` conecta mas a busca volta vazia.
  </Card>
</CardGroup>