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

# Conectar via Claude Code

> Configure o MCP Server da strattum.ai no Claude Code usando transporte stdio — processo local, sem latência de rede.

O Claude Code suporta servidores MCP via **transporte stdio**: o cliente inicia o servidor como um subprocesso e se comunica via stdin/stdout. Não é necessário expor nenhuma porta de rede.

## Pré-requisitos

* Claude Code instalado (`npm install -g @anthropic-ai/claude-code`)
* Python 3.12+ disponível no PATH
* Ambiente local da strattum.ai em execução (Memory API em `localhost:8002`, Knowledge API em `localhost:8003`)
* Repositório `strattum-ai` clonado localmente

<Tip>
  Para subir o ambiente local, consulte o `docker-compose.yml` em `strattum-deploy/starter/`. O MCP Server lê as variáveis de ambiente do processo em que é iniciado, não de um container separado — ele se conecta às APIs via rede local.
</Tip>

## Instalação do MCP Server

```bash theme={null}
# A partir do diretório raiz do repositório strattum-ai
cd services/mcp-server
pip install -e .
```

## Configuração no Claude Code

O Claude Code lê servidores MCP de dois arquivos de configuração — use o que melhor se aplica ao seu contexto:

<Tabs>
  <Tab title="Configuração global (~/.claude.json)">
    Aplica o servidor a **todos os projetos**. Ideal para uso cotidiano com a plataforma strattum.ai.

    Edite (ou crie) o arquivo `~/.claude.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "strattum": {
          "command": "python",
          "args": ["-m", "mcp_server.server"],
          "cwd": "/caminho/para/strattum-ai/services/mcp-server/src",
          "env": {
            "MCP_TRANSPORT": "stdio",
            "MEMORY_API_URL": "http://localhost:8002",
            "KNOWLEDGE_API_URL": "http://localhost:8003",
            "PYTHONPATH": "/caminho/para/strattum-ai/services/mcp-server/src"
          }
        }
      }
    }
    ```

    Substitua `/caminho/para/strattum-ai` pelo caminho absoluto do repositório na sua máquina.
  </Tab>

  <Tab title="Configuração por projeto (.claude/settings.json)">
    Aplica o servidor **apenas ao projeto atual**. Útil para restringir o contexto da strattum.ai a projetos específicos.

    Crie o arquivo `.claude/settings.json` na raiz do seu projeto:

    ```json theme={null}
    {
      "mcpServers": {
        "strattum": {
          "command": "python",
          "args": ["-m", "mcp_server.server"],
          "cwd": "/caminho/para/strattum-ai/services/mcp-server/src",
          "env": {
            "MCP_TRANSPORT": "stdio",
            "MEMORY_API_URL": "http://localhost:8002",
            "KNOWLEDGE_API_URL": "http://localhost:8003",
            "PYTHONPATH": "/caminho/para/strattum-ai/services/mcp-server/src"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Verificando a conexão

Após configurar, inicie o Claude Code no terminal:

```bash theme={null}
claude
```

O servidor strattum aparecerá na lista de ferramentas disponíveis. Para confirmar, peça ao Claude:

```
Liste as ferramentas MCP disponíveis.
```

A resposta deve incluir `search_entity`, `get_entity_context` e `search_knowledge`.

## Exemplos de uso

### Buscar uma entidade pelo nome

```
Use a ferramenta search_entity para encontrar a empresa "TechCorp" na base da strattum.
```

Resultado esperado:

```
Found 1 entity(-ies):

1. **TechCorp Soluções Ltda** (company)
   - entity_id: `ent_8f3a2b1c`
   - email: contato@techcorp.com.br
   - segment: enterprise
```

### Obter o contexto completo de um cliente

```
Busque o contexto completo da entidade ent_8f3a2b1c, incluindo relações de grafo.
```

O Claude chamará `get_entity_context` com `depth: "immediate"` e retornará o perfil consolidado, os eventos recentes e as empresas ou contratos relacionados.

### Consultar uma política na base de conhecimento

```
Pesquise na base de conhecimento o procedimento de onboarding para clientes enterprise.
```

O Claude chamará `search_knowledge` e retornará os trechos mais relevantes de documentos indexados, ranqueados por relevância semântica.

### Fluxo combinado em uma única pergunta

```
Preciso me preparar para uma reunião com a TechCorp.
Busque o perfil deles na Memory e também os nossos SLAs para clientes enterprise no Knowledge.
```

O Claude orquestra chamadas a `search_entity`, `get_entity_context` e `search_knowledge` em sequência, consolidando as informações em uma resposta coesa.

## Solução de problemas

<AccordionGroup>
  <Accordion title="O servidor strattum não aparece na lista de ferramentas" icon="triangle-exclamation">
    Verifique se o Python 3.12+ está no PATH e se o pacote está instalado:

    ```bash theme={null}
    python --version
    python -m mcp_server.server --help
    ```

    Se o comando falhar, reinstale as dependências:

    ```bash theme={null}
    cd /caminho/para/strattum-ai/services/mcp-server
    pip install -e .
    ```
  </Accordion>

  <Accordion title="Erro: 'Could not reach the Memory API'" icon="triangle-exclamation">
    O MCP Server não consegue conectar à Memory API. Confirme que o ambiente local está em execução:

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

    Ambos devem retornar `200 OK`. Se não estiverem rodando, suba o ambiente com:

    ```bash theme={null}
    cd strattum-deploy/starter
    docker compose up -d
    ```
  </Accordion>

  <Accordion title="Erro de PYTHONPATH ou módulo não encontrado" icon="triangle-exclamation">
    Certifique-se de que o `PYTHONPATH` na configuração aponta para o diretório `src/` do MCP Server, onde o módulo `mcp_server` está localizado:

    ```
    /caminho/para/strattum-ai/services/mcp-server/src
    ```

    Alternativamente, use o `cwd` apontando para esse mesmo diretório.
  </Accordion>
</AccordionGroup>