MCP Server

GetRaze ships a remote MCP server (Model Context Protocol, Streamable HTTP) so AI agent harnesses can operate your account through tools: search and update contacts and deals, read and answer conversations, pull reports, and talk to your AI employees.

Any MCP client works — Claude Code, Claude Desktop, Cursor, the OpenAI Agents SDK, n8n, or your own harness.

Endpoint

https://app.getraze.com/mcp

Transport: Streamable HTTP (stateless; every request carries the token). The server speaks both the 2025-06-18 and 2026-07-28 protocol revisions.

Authentication

The MCP server uses the same API keys as the REST API. Any valid key connects; what it can do is decided by its scopes (contacts:read, opportunities:write, …), exactly as on the REST API. Create or edit keys in Settings > API Keys.

Send the key as a Bearer token on every request:

Authorization: Bearer lr_live_xxxxxxxxxxxxx

No query string

Unlike the REST API, the MCP server rejects ?api_key= with 400. The MCP specification forbids tokens in the URL.

Each tool additionally requires the scope of the resource it touches (contacts:read, opportunities:write, …). tools/list only returns the tools your key can call, so a read-only key sees a read-only server. The full scope-to-tool map is on the Tools page.

Status	Meaning
401 + WWW-Authenticate: Bearer error="invalid_token"	Missing, invalid, expired or revoked key
403 + WWW-Authenticate: Bearer error="invalid_token"	The user who created the key is no longer active in the account
429 + Retry-After	Hourly rate limit of the key exhausted (only tools/call counts)

Connect your client

Claude Code

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

Cursor / Claude Desktop (mcp.json)

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

OpenAI Agents SDK

from agents import Agent, HostedMCPTool

agent = Agent(
    name="Sales assistant",
    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",
    })],
)

n8n

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

Then try: "How many deals do I have in the Proposal stage of the Sales pipeline?" — the agent will call pipelines_list and reports_funnel.

Conventions

• Every tool returns the same envelope. Success: { "ok": true, "data": …, "pagination"?: … }. Failure: { "ok": false, "error": { "code", "message", "details"? } } as an isError tool result, never a transport error — the model reads the message and corrects itself. The text content is the same JSON as structuredContent.
• Ids are UUIDs, dates are ISO 8601 (a date 2026-08-28 or a date-time 2026-08-28T00:00:00Z), lists take page (1-based) and limit (max 100). Unknown arguments are rejected (additionalProperties: false).
• Tools your key cannot call are not listed. Calling one anyway returns the JSON-RPC error Tool <name> not found; grant the scope (or enable the module) and reconnect.
• Write tools accept two extra arguments. dry_run: true validates and returns what would change with simulated: true, writing nothing. idempotency_key makes retries safe: the same key with the same arguments within 24 h returns the first result with replayed: true (see Idempotency).
• The author of every write is the user who created the API key — that is who appears on notes, sent messages and history entries.
• Deletes are not exposed. Use the REST API if you need them.
• Resources (getraze://account, pipelines, tags, users, sectors, agents, tool-catalog) hold reference data the model can read once, for clients that support resources (Claude Code: @getraze:pipelines). Every resource has a tool twin.
• Prompts: qualify_lead(contact_id) and daily_pipeline_review(pipeline_id?) are ready-made playbooks.

Error codes

On top of the REST error codes:

Code	Meaning
INSUFFICIENT_PERMISSIONS	Returned by contacts_add_tags when create_missing needs tags:write the key lacks
AMBIGUOUS	A name matched more than one record (e.g. a stage present in two pipelines) — details lists them
TAG_NOT_FOUND	Tag names that do not exist; pass create_missing: true (needs tags:write)
TOOL_ERROR	An AI-employee native action refused (message explains why)
NO_ACTIVE_CHANNEL	The agent's channel type has no connected channel, so it cannot be chatted with
SESSION_NOT_FOUND / SESSION_EXPIRED	Chat session ended or idle for more than 30 minutes
IDEMPOTENCY_CONFLICT / IDEMPOTENCY_KEY_REUSED	Same idempotency_key still in flight / used with different arguments

Audit

Every tools/call is recorded with its arguments, result, status, duration, dry_run and idempotency flags, and the acting user — in addition to the per-request usage log you already see under the key.