# Protocolo (/mcp/protocolo)

Detalhes técnicos pra quem quer chamar o servidor direto, sem um assistente no meio.

O Promptado MCP segue a especificação do [Model Context Protocol](https://modelcontextprotocol.io) no transporte Streamable HTTP, numa versão simplificada: sem sessão e sem streaming. Cada chamada é um `POST` com uma mensagem JSON-RPC 2.0, e a resposta vem inteira em JSON.

- **Endereço**: `https://app.promptado.com/api/mcp`

- **Método HTTP**: `POST`

, com 

`Content-Type: application/json`

.

- **Autenticação**: `Authorization: Bearer SUA_CHAVE`

, ou a chave no endereço (

`/api/mcp/SUA_CHAVE`

).

- **Versões do protocolo**: `2025-11-25`

, 

`2025-06-18`

, 

`2025-03-26`

e 

`2024-11-05`

. Se o cliente pedir outra, o servidor responde com a mais recente.

- **Métodos**: `initialize`

, 

`ping`

, 

`tools/list`

e 

`tools/call`

. Notificações (como 

`notifications/initialized`

) são aceitas e respondidas com 

`202`

.

- **Lotes**: Aceitos, pra compatibilidade com versões antigas do protocolo.

## Listar as tools

```bash
curl -s https://app.promptado.com/api/mcp \
  -H "Authorization: Bearer $PROMPTADO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

Cada tool vem com `name`, `description`, `inputSchema` (JSON Schema) e `annotations.readOnlyHint: true`.

## Chamar uma tool

**Requisição**

```bash
curl -s https://app.promptado.com/api/mcp \
  -H "Authorization: Bearer $PROMPTADO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_visibility",
      "arguments": { "brand_id": "8f1c…", "period": "30d", "llm_provider": "ChatGPT" }
    }
  }'
```

**Resposta**

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "{\"periodo_consultado\":{…}, …}" }],
    "isError": false
  }
}
```

O resultado da tool vem como JSON serializado dentro de `content[0].text`. Quando a consulta falha, `isError` vem `true` e o texto traz a mensagem. Veja [Limites e erros](/mcp/limites-e-erros).

## Acesso recalculado a cada chamada

O servidor não guarda sessão. Toda chamada confere a chave e recalcula as marcas que ela enxerga. Revogar a chave, tirar a pessoa da empresa ou desligar o MCP da empresa vale a partir da próxima chamada.