Servidor MCP

O GetRaze oferece um servidor MCP remoto (Model Context Protocol, Streamable HTTP) para harnesses de agentes de IA operarem a sua conta por tools: buscar e atualizar contatos e negócios, ler e responder conversas, puxar relatórios e conversar com os seus funcionários de IA.

Qualquer cliente MCP serve — Claude Code, Claude Desktop, Cursor, OpenAI Agents SDK, n8n ou o seu próprio harness.

Endpoint

https://app.getraze.com/mcp

Transporte: Streamable HTTP (stateless; toda requisição leva o token). O servidor fala as revisões 2025-06-18 e 2026-07-28 do protocolo.

Autenticação

O servidor MCP usa as mesmas chaves de API da API REST. Qualquer chave válida conecta; o que ela pode fazer é decidido pelos escopos dela (contacts:read, opportunities:write, …), exatamente como na API REST. Crie ou edite chaves em Configurações > Chaves de API.

Envie a chave como Bearer em toda requisição:

Authorization: Bearer lr_live_xxxxxxxxxxxxx

Sem query string

Diferente da API REST, o servidor MCP recusa ?api_key= com 400. A especificação MCP proíbe token na URL.

Cada tool exige ainda o escopo do recurso que toca (contacts:read, opportunities:write, …). O tools/list só devolve as tools que a sua chave pode chamar: uma chave só-leitura enxerga um servidor só-leitura. O mapa completo escopo → tool está na página Tools.

Status	Significado
`401` + `WWW-Authenticate: Bearer error="invalid_token"`	Chave ausente, inválida, expirada ou revogada
`403` + `WWW-Authenticate: Bearer error="invalid_token"`	O usuário que criou a chave não está mais ativo na conta
`429` + `Retry-After`	Limite por hora da chave esgotado (só `tools/call` conta)

Conecte o seu cliente

Claude CodeCursor / Claude Desktop (mcp.json)OpenAI Agents SDKn8n

bash

claude mcp add --transport http getraze https://app.getraze.com/mcp \
  --header "Authorization: Bearer lr_live_xxxxxxxxxxxxx"

json

{
  "mcpServers": {
    "getraze": {
      "url": "https://app.getraze.com/mcp",
      "headers": { "Authorization": "Bearer lr_live_xxxxxxxxxxxxx" }
    }
  }
}

python

from agents import Agent, HostedMCPTool

agent = Agent(
    name="Assistente comercial",
    tools=[HostedMCPTool(tool_config={
        "type": "mcp",
        "server_label": "getraze",
        "server_url": "https://app.getraze.com/mcp",
        "headers": {"Authorization": "Bearer lr_live_xxxxxxxxxxxxx"},
        "require_approval": "never",
    })],
)

text

Nó: MCP Client
Endpoint: https://app.getraze.com/mcp
Server Transport: HTTP Streamable
Authentication: Header Auth → Authorization: Bearer lr_live_xxxxxxxxxxxxx

Depois experimente: "Quantas oportunidades tenho em Proposta no funil Vendas?" — o agente vai chamar pipelines_list e reports_funnel.

Convenções

Toda tool devolve o mesmo envelope. Sucesso: { "ok": true, "data": …, "pagination"?: … }. Falha: { "ok": false, "error": { "code", "message", "details"? } } como resultado isError, nunca erro de transporte — o modelo lê a mensagem e se corrige. O conteúdo em texto é o mesmo JSON do structuredContent.
Ids são UUIDs, datas são ISO 8601 (data 2026-08-28 ou data-hora 2026-08-28T00:00:00Z), listas recebem page (a partir de 1) e limit (máx. 100). Argumento desconhecido é recusado (additionalProperties: false).
Tools que a sua chave não pode chamar não são listadas. Chamar mesmo assim devolve o erro JSON-RPC Tool <nome> not found; conceda o escopo (ou habilite o módulo) e reconecte.
Tools de escrita aceitam dois argumentos a mais. dry_run: true valida e devolve o que mudaria com simulated: true, sem gravar nada. idempotency_key deixa a repetição segura: a mesma chave com os mesmos argumentos em 24 h devolve o primeiro resultado com replayed: true (veja Idempotência).
O autor de toda escrita é o usuário que criou a chave de API — é ele que aparece em notas, mensagens enviadas e histórico.
Exclusões não são expostas. Use a API REST se precisar.
Resources (getraze://account, pipelines, tags, users, sectors, agents, tool-catalog) trazem dados de referência que o modelo lê uma vez, em clientes que suportam resources (Claude Code: @getraze:pipelines). Todo resource tem uma tool gêmea.
Prompts: qualify_lead(contact_id) e daily_pipeline_review(pipeline_id?) são roteiros prontos.

Códigos de erro

Além dos códigos da API REST:

Código	Significado
`INSUFFICIENT_PERMISSIONS`	Devolvido por `contacts_add_tags` quando `create_missing` precisa de `tags:write` e a chave não tem
`AMBIGUOUS`	Um nome casou com mais de um registro (ex.: etapa presente em dois funis) — `details` lista
`TAG_NOT_FOUND`	Etiquetas que não existem; passe `create_missing: true` (exige `tags:write`)
`TOOL_ERROR`	Uma ação nativa do funcionário de IA recusou (a mensagem explica)
`NO_ACTIVE_CHANNEL`	O tipo de canal do agente não tem canal conectado; não dá para conversar
`SESSION_NOT_FOUND` / `SESSION_EXPIRED`	Sessão de chat encerrada ou parada há mais de 30 minutos
`IDEMPOTENCY_CONFLICT` / `IDEMPOTENCY_KEY_REUSED`	Mesma `idempotency_key` ainda em curso / usada com argumentos diferentes

Auditoria

Toda tools/call fica registrada com argumentos, resultado, status, duração, flags de dry_run e idempotência e o usuário ator — além do log de uso por requisição que você já vê na chave.

Servidor MCP ​

Endpoint ​

Autenticação ​

Conecte o seu cliente ​

Convenções ​

Códigos de erro ​