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

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

***

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

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

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

> **[Claude Code](https://docs.strattum.ai/mcp-server/claude-code.md)**
>
> Configuração para Claude Code CLI

> **[Microsoft Copilot](https://docs.strattum.ai/mcp-server/microsoft-copilot.md)**
>
> Configuração para Microsoft Copilot Studio

> **[ChatGPT](https://docs.strattum.ai/mcp-server/chatgpt.md)**
>
> Configuração para ChatGPT com MCP

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

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

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


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