> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strattum.ai/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.

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

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

**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"
      }
    }
  }
}
```

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

> **O servidor strattum não aparece na lista de ferramentas**
>
> 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 .
> ```

> **Erro: 'Could not reach the Memory API'**
>
> 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
> ```

> **Erro de PYTHONPATH ou módulo não encontrado**
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.