MCP reference

Endpoint

POST https://api.usereachout.com/mcp
Content-Type: application/json
Authorization: Bearer <api_key>

Transports: http (single request/response) and sse (streaming). Server version is advertised in the initialize response under serverInfo.

Delegated OAuth

Control-plane tools use OAuth 2.1 Authorization Code with PKCE S256. Discover authorization metadata from the MCP endpoint, send the exact MCP audience, and obtain browser consent from the acting user. Request mcp:read for reads, both mcp:write and mcp:governancefor governance writes, and offline_access only when refresh is required.

Access tokens are short-lived and refresh tokens rotate. Every delegated call supplies an explicitorganizationId or projectId; there is no stored organization or project context. Organization API keys remain for legacy organization-scoped data tools and are limited to their explicit project grants for get_organization_overview. Governance tools require a delegated user and otherwise return the stable MCP_USER_DELEGATION_REQUIRED error.

Get an API key

Sign in to the Studio and go to Organization settings → API keys. Click Generate API key, give the key a label (e.g.Claude Desktop), and copy the rok_live_… plaintext from the modal — it is shown exactly once. The server stores only the SHA-256 hash and a 12-char visible prefix, so a key cannot be recovered if you lose it.

The same panel lists every active key with its prefix, label, and last-used time. Revoking a key invalidates the server-side context cache immediately, so any client using it stops authenticating on the next request. Owner/admin role required.

Filtering analytics by website

Analytics tools require a stable projectId. Discover accessible projects withlist_projects; MCP does not persist or switch an active project. An optionalclientId further restricts results to a tracking client owned by that project.

Discover the IDs first with list_tracking_clients, then pass one in:

# 1. list projects
{"method":"tools/call","params":{"name":"list_projects","arguments":{"organizationId":"org_example"}}}

# 2. query one concrete project
{"method":"tools/call","params":{
  "name":"get_analytics_overview",
  "arguments":{
    "projectId":"project_01J6Y0N8V4J5Q2M7K3R9T6W1XA",
    "range":"30d",
    "clientId":"cl_example"
  }
}}

get_organization_overview is a read-only aggregate over the caller's currently authorized project grants. It is not an all-project data mode and never accepts caller-supplied project IDs.

Client setup

Use the same endpoint and bearer token in every MCP client. Keep the key out of committed project files unless you reference it through an environment variable.

Claude CLI / Claude Code

claude mcp add --transport http reachout https://api.usereachout.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

claude mcp list

Codex

# ~/.codex/config.toml
[mcp_servers."reachout"]
url = "https://api.usereachout.com/mcp"
[mcp_servers."ReachOut".headers]
Authorization = "Bearer YOUR_API_KEY"

# Then verify:
codex mcp list

Claude Desktop

{
  "mcpServers": {
    "reachout": {
      "type": "http",
      "url": "https://api.usereachout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor, LM Studio, and other MCP clients

{
  "mcpServers": {
    "reachout": {
      "transport": "http",
      "url": "https://api.usereachout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Some clients call the key transport; others call ittype. Use HTTP / Streamable HTTP when the client asks for the transport.

Authentication

Every tools/call requires a bearer token. Three token shapes are accepted:

Unauthenticated methods: initialize, tools/list, ping.

Organization scoping

Delegated control-plane tools include an organizationId or projectIdparameter. Authorization is resolved per request:

1. Delegated user — the OAuth token identifies the consenting user and granted scopes.
2. Explicit target — organizationId or a project resolved from projectId.
3. Legacy key — legacy data tools use only the organization issued to that key.

Membership and project permissions are checked live on every delegated call.

Response envelope

Every successful tool response is a single text block. The first two lines are a human-readable header showing the organization addressed by the call; the rest is JSON.

[organization] Acme Inc (id: org_abc123)
--------------------------------------------------------------
{
  "organization": { "id": "org_abc123", "name": "Acme Inc", "slug": "acme" },
  "result": { /* tool-specific payload */ }
}

The header is part of the text content the model sees, so any well-behaved client will surface the addressed organization to the user on every tool call. For programmatic parsing, strip the header and decode the JSON body — result holds the tool payload, organizationis always present.

Errors are emitted with isError: true and the same header prefix where possible.

Tools — organization management

These tools require delegated OAuth and explicit organization targets.

There is no session-level organization selector. Delegated control-plane calls pass the target identifier on every request; legacy data tools remain scoped to the organization issued to the API key.

Tools — domain surface

Legacy data tools are explicitly organization-scoped to their API key. Control-plane tools require delegated OAuth and explicit targets.

Full JSONSchema for every tool lives at /mcp-manifest.json.

Error codes

Changelog

v2.0.0

Delegated OAuth 2.1 control plane with explicit organization and project targets. Governance tools require scoped user consent; legacy data tools remain organization-scoped until their cutovers.

v1.0.0

Initial release. Per-tool organizationId inputs, org-scoped API keys only.

Next steps

• Local AI quickstart — Ollama, LM Studio, Claude Desktop, Cursor configs.
• mcp-manifest.json — machine-readable tool schema.
• llms-full.txt — data model and REST endpoints.