MCP server

Railhook serves a Model Context Protocol server at /mcp. An agent connected to it can see why a delivery failed, replay it, register an endpoint or send a test event, in one project, with read-only or read & write access.

Where	MCP server URL
Railhook Cloud	https://railhook.io/mcp
Self-hosted	<your origin>/mcp, e.g. https://hooks.example.com/mcp

Wellknown, a public index of MCP servers, checks the Cloud server on a schedule and publishes its uptime.

Two ways in, with the same tools and limits. The transport is Streamable HTTP.

• Sign in. claude.ai, Claude Desktop connectors and ChatGPT send you to Railhook to approve them for a project.
• A project API key. Claude Code, Cursor and the @railhook/mcp stdio bridge send the key as a header.

Connect by signing in

claude.ai / Claude Desktop

1. Open Settings → Connectors (in newer versions Customize → Connectors) and add a custom connector.
2. Name it Railhook and enter the URL https://railhook.io/mcp. Leave the OAuth client ID and secret empty: Claude registers itself.
3. Click Connect. Railhook opens; sign in if you are not already.
4. Pick the organization and project, choose Read Only or Read & Write, and click Connect. You are sent back to Claude.

A connector added on claude.ai is also available in Claude Desktop and the mobile apps signed in to the same account.

ChatGPT

1. Turn on developer mode: Settings → Apps → Advanced settings → Developer mode. On a Business or Enterprise workspace an admin may have to allow custom connectors first.
2. Create a connector with the URL https://railhook.io/mcp and OAuth as its authentication.
3. ChatGPT opens Railhook. Sign in, pick the organization and project, choose the access, and click Connect.

An approval carries what an API key carries: one project and one scope. An app connected read-only cannot send an event or replay a delivery. The menus above move between app versions; the URL does not.

Caution

The app name on the consent screen is whatever the app registered. Check the host shown under it, the address that gets access, before you click Connect.

Who can connect what

Any member of the organization can connect an app read-only. Read & write takes the Owner or Developer role, the same roles that may create an API key. A connected app works only while the person who approved it could still approve it: removing or suspending them, or moving a Developer down to Viewer, stops the apps they connected.

Access tokens last an hour and the app renews them itself.

See and disconnect apps

A project’s connected apps are listed under API Keys, below the keys, with the access each has, the host it signed in from, who approved it and when it was last used. Disconnect stops it at once. Connecting and disconnecting are written to the organization’s audit log.

Connect with an API key

Tip

Start with a READ_ONLY key: read tools work, every tool that changes something is refused. Create a READ_WRITE key when the agent should act. See Authentication for keys and scopes.

Claude Code

claude mcp add --transport http railhook https://railhook.io/mcp \
  --header "Authorization: Bearer $RAILHOOK_API_KEY"

Add --scope user to have it in every project. claude mcp list shows whether it connected.

Cursor

.cursor/mcp.json

{
  "mcpServers": {
    "railhook": {
      "url": "https://railhook.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:RAILHOOK_API_KEY}"
      }
    }
  }
}

~/.cursor/mcp.json makes it available in every project. ${env:RAILHOOK_API_KEY} is read from Cursor’s environment, so the key stays out of the file.

Claude Desktop (config file)

Servers in Claude Desktop’s config file are local processes, so they use the bridge. It needs Node.js 18 or later. To connect by signing in instead, add a connector as above.

claude_desktop_config.json

{
  "mcpServers": {
    "railhook": {
      "command": "npx",
      "args": ["-y", "@railhook/mcp"],
      "env": {
        "RAILHOOK_API_KEY": "your-project-api-key"
      }
    }
  }
}

Open the file from Settings → Developer → Edit Config, then restart Claude Desktop.

Other clients

A client that supports remote servers needs the URL and one header, either of:

Authorization: Bearer <project API key>
X-API-Key: <project API key>

A client that only starts local processes runs the bridge instead:

RAILHOOK_API_KEY=<project API key> npx -y @railhook/mcp

Self-hosted

Replace https://railhook.io with your own origin in the URL. For the bridge, set RAILHOOK_BASE_URL next to the key:

claude_desktop_config.json

"env": {
  "RAILHOOK_API_KEY": "your-project-api-key",
  "RAILHOOK_BASE_URL": "https://hooks.example.com"
}

Signing in needs two things. APP_BASE_URL must be the public HTTPS origin, because the app is redirected there and checks it as the issuer. And the instance must be reachable from the internet, because claude.ai and ChatGPT connect from their own servers. An instance on a private network takes API keys only.

Both switches are on by default. MCP_ENABLED=false in .env turns /mcp off; MCP_OAUTH_ENABLED=false keeps it on for API keys and turns signing in off. See Configuration.

Tools

Every tool acts on the project of the key or connected app. No tool takes a project id, so an agent cannot reach another project, even in the same organization.

Tool	What it does	Access
list_endpoints	The project’s endpoints, with whether each is enabled and verified	Any
list_subscriptions	Which endpoint receives which event type, optionally for one endpoint	Any
list_deliveries	Deliveries, newest first, filtered by status, endpoint, event, event type or time	Any
get_delivery	One delivery and every attempt at it: status code, error, duration, request and response bodies	Any
send_event	Sends an event; one delivery is created per enabled subscription to its type	READ_WRITE
create_endpoint	Registers an endpoint and returns its signing secret, once	READ_WRITE
create_subscription	Subscribes an endpoint to an event type	READ_WRITE
replay_delivery	Puts a FAILED or DLQ delivery back on its retry ladder; dryRun shows what would be sent	READ_WRITE

Read tools carry the read-only hint, so a client may run them without asking. Results use the shapes in the API reference, with attempt bodies cut to 2,000 characters. A list comes as content plus page, size, totalElements and totalPages.

API limits apply: send_event counts against the project’s rate limit and event quota, create_endpoint against the endpoint limit.

Troubleshooting

Symptom	Fix
401 when the client connects with a key	The key is wrong, revoked or expired, or it belongs to another instance than the URL. Create a new key
The app asks you to sign in again	The app was disconnected, or the person who approved it was removed, suspended or lost the role it needs. Connect it again
“This request has expired” on the consent screen	The screen was open for more than ten minutes, or already answered. Start connecting again from the app
“This app can’t be connected”	The app asked to return somewhere it did not register. Remove the connector in the app and add it again
A tool answers that the key or app is read-only	Expected for write tools. Use a READ_WRITE key, or reconnect the app with Read & Write
404 at /mcp or /.well-known/oauth-authorization-server on a self-hosted instance	MCP_ENABLED or MCP_OAUTH_ENABLED is false, or the instance predates it. Upgrade it
The bridge exits with RAILHOOK_API_KEY is not set	Put the key in the env block of the client’s config, not in args