MCP integration

Pushrail runs a hosted Model Context Protocol server so AI agents and IDEs (Claude, Cursor, Windsurf, Codex) can read and operate your Pushrail workspace through a set of tools. The server is hosted at https://mcp.pushrail.io over Streamable HTTP. There are two ways to connect: browser sign-in (the default — no key to paste) and an MCP API key header for CI and headless agents. Either way, your workspace role or the key's scope sets the ceiling of what the agent can do.

Both connection methods are account-wide: they're tied to your workspace, not to a single environment. You don't pick an environment when you connect. Instead, the agent names the target environment (Development, Staging, or Production) on each individual tool call — required when it writes, optional when it reads. See Specifying an environment per call below.

Connect

Sign in from your editor (recommended)

The simplest way to connect is to point your client at the server URL with no key. The first time the agent connects, it opens your browser to approve access. On the approval screen you sign in and pick the workspace the agent should operate in. There's no environment to choose at connect time — the agent names the environment per action afterward. Once you approve, the agent is connected — there's nothing to copy or paste, and sessions refresh automatically so you don't have to sign in again every time.

Use the CLI to write the config for a supported client:

pushrail mcp install --client claude   # or cursor | windsurf | codex

install merges into your existing client config rather than clobbering it. To see (and copy) the config without writing a file, run:

pushrail mcp config

When you're signed in via the browser, the printed config is just the server URL — no header:

{
  "mcpServers": {
    "pushrail": {
      "type": "http",
      "url": "https://mcp.pushrail.io"
    }
  }
}

Point a fresh client at that URL and it will walk you through the browser approval on first use.

MCP API key header (CI and headless agents)

For CI jobs, service agents, or any environment without a browser, supply an MCP API key as an Authorization header instead. MCP API keys are account-wide (they begin with pmk_) and are minted in the dashboard at MCP API keys. They're used to connect AI agents, the CLI, and the MCP server — distinct from the environment-scoped API keys your backend uses to send events. The key sets the agent's workspace and its ceiling of capabilities; the environment is named per tool call, not by the key.

{
  "mcpServers": {
    "pushrail": {
      "type": "http",
      "url": "https://mcp.pushrail.io",
      "headers": { "Authorization": "Bearer pmk_…" }
    }
  }
}

pushrail mcp config includes this header automatically when you're logged in (or have an MCP API key set); otherwise it omits it and you paste your own key. Create one from MCP API keys in the dashboard with a read or manage scope — see MCP API keys below.

MCP API keys

MCP API keys are the credential for connecting AI agents, the CLI, and the MCP server without a browser. They're account-wide: tied to your workspace, never to a single environment. They begin with pmk_ and are distinct from the environment-scoped API keys your backend uses to send events.

Create one from MCP API keys in the dashboard:

1. Open MCP API keys, click New key, and give it a name (for example, "CLI on my laptop").
2. Choose a scope:
   • Read — the agent can view destinations, deliveries, and schemas, but can't change anything. The session tops out at read-only.
   • Manage — the agent can also create and change configuration. The session can reach write operations.
3. Copy the key. The full secret is shown once at creation and never again — if you lose it, revoke it and mint a new one. Only a hash is stored, so a leaked key can be revoked but not recovered.

Paste the key into your MCP client's Authorization header as shown above, or hand it to the CLI. Revoke a key from the same page at any time; the next request with it returns 401.

When to use which key

| Use case | Credential | |---|---| | Connect an AI agent, the CLI, or the MCP server | MCP API key (pmk_…), account-wide | | Send events from your backend / product server | Environment-scoped API key (pr_dev_… / pr_sta_… / pr_pro_…) |

MCP API keys never send production traffic on their own — they let an agent operate your workspace and name the environment per action. Environment-scoped keys carry their environment in the key itself and are what your application code uses to emit events.

Specifying an environment per call

Because the connection is account-wide, the agent chooses the environment on each action, not once at connect time. Every tool that touches environment-scoped resources (destinations, events, deliveries) takes an environment argument — one of DEVELOPMENT, STAGING, or PRODUCTION:

• Writes require it. create_destination and send_test_event must be given an explicit environment. If the agent omits it, the call is rejected before anything happens — there's no implicit default, so a write can never land in the wrong environment by accident.
• Reads make it optional. list_destinations and list_deliveries accept environment to scope the result; omit it to list across all environments at once. Each returned row carries its own environment so the agent can tell them apart.
• By-id and workspace-wide tools don't take it. Tools that act on a single record by id (retry_delivery, get_destination, get_delivery, get_destination_health) derive the environment from the record. Tools on workspace-wide resources (channels, schemas, portal sessions) aren't environment-scoped at all.

Safety modes

Every tool declares a required safety mode on a three-rung ladder:

readonly  <  allow-writes  <  allow-deletes

A session's effective mode is the lower of two things:

• the ceiling of how you connected, and
• what the request asks for via the x-pushrail-mcp-mode header.

How the ceiling is set depends on how you connected:

• Browser sign-in — the ceiling is your workspace role. A viewer gets read-only; a member can also write; an admin or owner can also delete. You can't grant an agent more than your own role allows.
• MCP API key header — the ceiling is set by the key's scope: a manage-scoped key tops out at allow-writes; a read-scoped key is readonly.

With no header, the session defaults to that ceiling. The header can only lower the mode below the ceiling, never raise it, so an agent can be granted less than you can do, never more. A tool whose required mode exceeds the session mode is refused with a structured message explaining what to change.

Tool surface

The hosted server registers the following tools. Each runs only when the session mode is at or above its required mode.

Context

| Tool | Required mode | Description | |---|---|---| | get_pushrail_context | readonly | Return the current auth method, principal, tenant, scopes, the per-call environment mode and available environments, and the capabilities enabled for this session. | | list_workspaces | readonly | List the workspaces accessible to this credential (today a credential is scoped to one). | | list_projects | readonly | List environments (Development, Staging, Production). |

Channels (customer accounts)

| Tool | Required mode | Description | |---|---|---| | list_channels | readonly | List customer accounts; each routes a workspace's events to its own destinations. | | get_channel | readonly | Fetch one customer account by UUID or external id. | | create_channel | allow-writes | Create a customer account; its external id is your stable identifier for the end customer. | | list_sources | readonly | List the distinct source values seen on recent events. |

Destinations

| Tool | Required mode | Description | |---|---|---| | list_destinations | readonly | List destinations, optionally filtered by environment (omit to list across all environments), channel, type, or status. | | get_destination | readonly | Fetch one destination including its type, status, and environment. | | create_destination | allow-writes | Create a destination on a channel; requires the target environment; config holds the adapter-specific connection fields. | | get_destination_health | readonly | Return the rolling health status and success rate for a destination. |

Events

| Tool | Required mode | Description | |---|---|---| | send_test_event | allow-writes | Ingest a single event for a channel to verify routing and delivery end-to-end; requires the target environment. | | generate_sample_event | readonly | Produce a deterministic sample payload for an event type, plus SDK and CLI snippets. | | validate_event_payload | readonly | Check that an event envelope is well-formed before sending it. |

Deliveries

| Tool | Required mode | Description | |---|---|---| | list_deliveries | readonly | List recent deliveries, optionally filtered by environment (omit to list across all environments), destination, event, or status. | | get_delivery | readonly | Fetch one delivery record including its full attempt history. | | explain_delivery_failure | readonly | Diagnose why a delivery failed, whether it's retryable, and how to fix it. | | retry_delivery | allow-writes | Requeue a failed or dead-lettered delivery for another attempt. |

Schemas

| Tool | Required mode | Description | |---|---|---| | list_schemas | readonly | List the workspace's event-schema catalog. | | get_schema | readonly | Fetch one event schema by id or event type. | | create_schema | allow-writes | Register a new event schema in the catalog. | | validate_schema | readonly | Check a schema document, and optionally a payload against it. |

Security

| Tool | Required mode | Description | |---|---|---| | verify_signature | readonly | Recompute Pushrail's HMAC-SHA256 webhook signature and compare it constant-time against a provided header. |

Portal

| Tool | Required mode | Description | |---|---|---| | create_portal_session | allow-writes | Mint an embed/portal link so a channel's end customer can manage their own destinations. |

Documentation

| Tool | Required mode | Description | |---|---|---| | get_integration_guide | readonly | Return a step-by-step integration guide for a given language. | | get_sdk_example | readonly | Return a focused code example for a single SDK operation. | | get_cli_example | readonly | Return the real CLI command(s) for a given workflow. | | get_destination_setup_guide | readonly | Return the fields, credentials, security notes, and common failure modes for a destination type. |

Safety

| Tool | Required mode | Description | |---|---|---| | check_required_permissions | readonly | Report whether the session can perform an operation, which permissions are missing, and how to enable them. | | validate_cli_command | readonly | Heuristically assess a CLI command for risk before running it. |

Example prompts

When the session can reach allow-writes (a member-or-above role via browser sign-in, or a manage-scoped MCP API key), an agent can chain tools to do real work. Tell it which environment to act in — or it'll ask before any write:

• "Set up a webhook destination for customer cust_42 in Staging and send a test event." The agent calls get_channel, create_destination and send_test_event (each with environment: "STAGING"), and reads back the result with list_deliveries.
• "Explain why delivery dlv_… failed and whether it's worth retrying." The agent calls get_delivery then explain_delivery_failure; if retryable and the session allows writes, retry_delivery.
• "Which destinations are unhealthy this week?" The agent calls list_destinations then get_destination_health per destination, all read-only.

See the OAuth connect guide for a full walkthrough of browser sign-in, and the CLI command reference for pushrail login, pushrail mcp install, and pushrail mcp config.