The RALPH MCP server

What it offers

The server is a thin relay over the REST API. Each tool matches something you’d ask for, like “book it” or “ground G-CDXX”, not an endpoint. It calls the API with your own credential, so the agent can never do more than you could yourself, and the audit trail records you as the one who acted.

• Task-shaped tools. A tool may make several API calls, but never hides an outcome: a booking held for approval is reported as held, and why.
• Preview before you commit. check_booking answers “could Sam book G-CDXX on Saturday?” without booking anything.
• Its own retries are safe. The server sends each API call an Idempotency-Key and retries under it, so a network blip never books twice. Calling create_booking again is a new booking, unless the agent passes the same idempotency_key both times, within 24 hours.
• Set-up by interview. Ask the agent to set up your organisation. It runs RALPH’s setup interview, served by the server itself as the setup_guide tool and the ralph-org-setup prompt.

Connect it

The server is at:

https://mcp.ralphops.ai/mcp

Each app signs in through RALPH’s own OAuth server, with a pre-registered client ID and no client secret. You sign in with Google, then pick the organisation the connection acts in. The token is scoped to you, in that one organisation.

Claude (claude.ai and Claude Desktop)

1. Open Customize → Connectors and add a custom connector.
2. Set the URL to https://mcp.ralphops.ai/mcp.
3. Under Advanced settings, set the OAuth Client ID to claude and leave the client secret blank.
4. Connect. Sign in, then pick your organisation.

Claude Code

claude mcp add --transport http --client-id claude-code --callback-port 8766 \
  ralph https://mcp.ralphops.ai/mcp

Run /mcp in Claude Code to sign in. The callback port must be 8766, the port registered for claude-code.

For an unattended run, send an agent key instead of signing in. Mint one with the CLI:

claude mcp add --transport http ralph https://mcp.ralphops.ai/mcp \
  --header "Authorization: Bearer rk_…"

ChatGPT

Needs ChatGPT Plus or higher, which offers developer mode. On Enterprise and Education, a workspace admin grants it first.

1. Open Settings → Security and login and turn on Developer mode.
2. Go to Plugins, select +, enter https://mcp.ralphops.ai/mcp and choose OAuth.
3. Set the client ID to chatgpt and leave the client secret blank.
4. Before connecting, check the redirect URI the connection’s page shows. RALPH accepts https://chatgpt.com/connector_platform_oauth_redirect. If yours is a per-connector https://chatgpt.com/connector/oauth/… address instead, send it to us first: sign-in fails until RALPH registers it.
5. Connect. Sign in, then pick your organisation.

Then start a new chat, turn on the connection and ask ChatGPT to set up your organisation.

Tools

Tool	Ask it
whoami	“Who am I acting as, in which organisation?”
find_availability	“When are the R44 and an instructor both free on Saturday?”
get_schedule	“What’s on for G-CDXX this week?”
check_booking	“Could Sam book G-CDXX on Saturday, 10:00 to 11:00?”
create_booking	“Book it.”
reschedule_booking	“Move it to 14:00.”
cancel_booking	“Cancel Sam’s Saturday slot.”
approve_booking, deny_booking	“Approve the held trial lesson.”
explain_booking	“Why is this booking held?”
list_fleet	“Which aircraft are online?”
ground_aircraft, unground_aircraft	“Ground G-CDXX, mag drop.”
log_flight	“Log yesterday’s tech-log line for G-CDXX.”
find_people	“List the instructors.”
grant_pilot_authorization, revoke_pilot_authorization, list_pilot_authorizations	“Sam is good for R44 self-hire.”
list_calendar_feeds, create_calendar_feed, rotate_calendar_feed, revoke_calendar_feed	“Put my bookings in my calendar.”
setup_guide	“Set up my organisation.”
add_aircraft, update_aircraft, adjust_meter	“Add G-CDXX to the fleet.”
add_person, update_person, set_person_roles	“Add Sam as an instructor.”
define_category, list_categories, update_category	“We do trial lessons.”
add_availability_rule, update_availability_rule, delete_availability_rule, list_availability_rules	“We’re open 09:00 to 17:00, Tuesday to Saturday.”
write_policy, list_policies, update_policy	“Dual bookings need an instructor.”
add_member, list_members, revoke_member	“Let Sam sign in.”
update_org	“We’re in Europe/London, not UTC.”

The tool surface is versioned. New arguments are optional, and a breaking change gets a new tool name, so an app holding an older tool list keeps working. Apps cache the tool list, so new tools can take a while to appear. An app on the 2026-07-28 MCP version is told the list is fresh for an hour. With an older one, starting a new chat or reconnecting the connector may help, but some keep the old list for longer.

Errors and hints

Errors reach the agent as they left the API, so it can negotiate rather than guess.

• A slot is taken: 409 booking-conflict, with the bookings in the way, so the agent can offer another time.
• A rule blocks the booking: 422 booking-blocked, with each failed check and a hint that resolves it, such as the authorization Sam needs.
• Something only you can say: urn:ralph:mcp:needs-input, before anything is written, listing each missing field and the question to ask. The agent asks you and tries again. A registration or a meter reading is never guessed.
• Signed out: an expired or revoked token gets 401, and the app signs you in again. An agent key has no sign-in to fall back on: when it expires or is revoked, mint a new one and put it in the connection’s header.
• The wrong organisation: a connection acts in the one organisation you picked. Disconnect, reconnect, and pick the right one.