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

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

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

{
  "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:

{
  "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:

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: [e-mail]
   - 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:

python --version
python -m mcp_server.server --help

Se o comando falhar, reinstale as dependências:

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:

curl http://localhost:8002/healthz
curl http://localhost:8003/healthz

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

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.