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

> Adaptador Model Context Protocol que expõe Memory e Knowledge como ferramentas para LLMs via SSE.

O **MCP Server** é o adaptador Model Context Protocol da strattum.ai. Ele expõe os produtos Memory e Knowledge como ferramentas MCP padronizadas, permitindo que agentes de IA (Claude, Microsoft Copilot, ChatGPT) acessem contexto de entidades e documentos corporativos diretamente durante uma conversa.

## Base URL

```
http://localhost:8005
```

Em produção, o endereço é configurado no deployment BYOC do cliente.

## Autenticação

O MCP Server exige autenticação via Bearer token no endpoint SSE.

```http theme={null}
Authorization: Bearer <MCP_API_KEY>
```

A chave é configurada pela variável de ambiente `MCP_API_KEY` no servidor. Clientes sem token válido recebem `401 Unauthorized`.

## Ferramentas MCP expostas

O servidor define três ferramentas no protocolo MCP:

| Ferramenta           | Serviço       | Descrição                                                              |
| -------------------- | ------------- | ---------------------------------------------------------------------- |
| `get_entity_context` | Memory API    | Retorna o contexto Markdown assembled de uma entidade pelo `entity_id` |
| `search_entity`      | Memory API    | Busca entidades por email, nome ou texto livre                         |
| `search_knowledge`   | Knowledge API | Busca semântica sobre documentos indexados                             |

<Note>
  As ferramentas são definidas pelo protocolo MCP, não pelo OpenAPI. Para configurar um cliente MCP, aponte para o endpoint SSE — não para a especificação OpenAPI.
</Note>

***

## GET /sse

Endpoint de transporte SSE (Server-Sent Events) para o protocolo MCP. Clientes MCP conectam aqui para receber definições de ferramentas e enviar chamadas.

### Headers obrigatórios

| Header          | Tipo   | Descrição              |
| --------------- | ------ | ---------------------- |
| `Authorization` | string | `Bearer <MCP_API_KEY>` |

### Exemplos de configuração por cliente

<CodeGroup>
  ```json Claude Desktop (claude_desktop_config.json) theme={null}
  {
    "mcpServers": {
      "strattum": {
        "url": "http://localhost:8005/sse",
        "headers": {
          "Authorization": "Bearer <MCP_API_KEY>"
        }
      }
    }
  }
  ```

  ```json Claude Code (.claude/mcp.json) theme={null}
  {
    "mcpServers": {
      "strattum": {
        "type": "sse",
        "url": "http://localhost:8005/sse",
        "headers": {
          "Authorization": "Bearer <MCP_API_KEY>"
        }
      }
    }
  }
  ```
</CodeGroup>

Para instruções detalhadas de configuração por cliente, consulte:

<CardGroup cols={3}>
  <Card title="Claude Code" icon="terminal" href="/mcp-server/claude-code">
    Configuração para Claude Code CLI
  </Card>

  <Card title="Microsoft Copilot" icon="microsoft" href="/mcp-server/microsoft-copilot">
    Configuração para Microsoft Copilot Studio
  </Card>

  <Card title="ChatGPT" icon="robot" href="/mcp-server/chatgpt">
    Configuração para ChatGPT com MCP
  </Card>
</CardGroup>

### Resposta

**200 OK** — stream SSE estabelecido

O cliente recebe eventos no formato SSE:

* `event: tool_list` — lista de ferramentas disponíveis
* `event: tool_result` — resultado de uma chamada de ferramenta

**401 Unauthorized** — token ausente ou inválido

```json theme={null}
{ "detail": "Missing or invalid MCP_API_KEY" }
```

***

## GET /healthz

Verifica se o MCP Server está rodando e se as APIs upstream (Memory e Knowledge) estão acessíveis.

### Exemplos de chamada

<CodeGroup>
  ```bash cURL theme={null}
  curl http://localhost:8005/healthz
  ```
</CodeGroup>

### Resposta

**200 OK** — todos os serviços acessíveis

```json theme={null}
{
  "status": "ok",
  "memory_api": "ok",
  "knowledge_api": "ok"
}
```

**503 Service Unavailable** — uma ou mais APIs upstream inacessíveis

```json theme={null}
{
  "status": "degraded",
  "memory_api": "ok",
  "knowledge_api": "unreachable"
}
```

***

## Fluxo típico de um agente

O diagrama abaixo mostra como um agente usa o MCP Server para responder uma pergunta sobre um cliente:

```
Usuário: "Me fale sobre a Maria Silva da TechCorp"
     │
     ▼
Agente chama: search_entity(name="Maria Silva")
     │
     ▼
MCP Server → Memory API POST /v1/memory/search
     │
     ◄── entity_id: "3fa85f64-..."
     │
Agente chama: get_entity_context(entity_id="3fa85f64-...")
     │
     ▼
MCP Server → Memory API GET /v1/memory/entity/{id}/context
     │
     ◄── Markdown com perfil, relações e timeline
     │
Agente sintetiza resposta para o usuário
```

Para perguntas sobre documentos corporativos:

```
Usuário: "Qual é a política de SLA para clientes Enterprise?"
     │
     ▼
Agente chama: search_knowledge(query="política SLA Enterprise", top_k=5)
     │
     ▼
MCP Server → Knowledge API POST /v1/knowledge/search
     │
     ◄── chunks rankeados por similaridade coseno
     │
Agente sintetiza resposta a partir dos chunks
```