Connect Claude or ChatGPT to Gravity Rail
Gravity Rail runs an MCP (Model Context Protocol) server. Add it as a connector in an AI assistant, and the assistant can work in your Gravity Rail workspaces as you, with your role in each workspace.
The server URL is:
https://api.gravityrail.com/mcp
Add the connector
claude.ai — open Settings → Connectors, choose Add custom connector, paste the server URL and save. Then choose Connect.
ChatGPT — in the connector settings, create a custom connector, paste the server URL and choose OAuth. Custom connectors may need developer mode; see OpenAI's help for your plan.
Other MCP clients — use the server URL with the Streamable HTTP transport.
The client discovers the authorization server from the server's
401 response and signs you in with OAuth. No API key is needed.
For clients that set OAuth's resource parameter, this server accepts only
https://api.gravityrail.com and https://api.gravityrail.com/mcp in production.
Use the MCP URL for this connector. Other values return invalid_target.
Choose what the connector can reach
When you connect, Gravity Rail asks you to sign in and shows a consent screen. Choose the organizations and workspaces the connector may reach:
- an organization covers every workspace in it, including ones created later;
- a workspace covers that workspace only.
If an organization requires single sign-on, you sign in with it on the consent screen. Review, narrow or remove a connection at any time in the apps section of your account profile.
An organization admin can limit which connectors reach the organization in Settings → MCP Server → AI connectors. An organization that does not allow your connector shows as unavailable on the consent screen.
What the assistant can do
The connector offers a small, fixed set of tools:
list_workspaces,list_organizations,list_billing_organizations— what the connection can reach;tool_search— find a capability in one workspace, such as "list workflows" or "create form";readandwrite— run a tool thattool_searchfound;invite_org_member,list_organization_products,create_organization,create_workspace,search_phone_numbers,purchase_phone_numberand the support-request tools — account-level tasks.
Ask the assistant in plain language, for example: "In the Intake workspace,
list the active workflows." It starts with list_workspaces, finds a tool
with tool_search, and runs it with read or write.
Every call runs as you. The assistant can never do more than your role allows in that workspace, and never more than the scopes you granted the connector.
Don't send PHI to a third-party AI service unless you have a BAA with that provider. Gravity Rail does not know which AI service, plan or model sits behind a connector, so it does not block one; that decision is yours.
Some things are not available through the connector yet: running code and browser control.
Writes that need confirmation
Most writes run as soon as the assistant calls them. Whether your assistant app asks you first is a setting in that app. Some writes always ask you first: the calls Gravity Rail asks about even in Auto approve. These are a write that changes a patient's own record, sends a message to a patient, publishes a Workflow, changes who can see or do what, or deletes, revokes or releases something.
For these, your assistant app shows a confirmation with the tool, the workspace it acts in, why it asks and every argument of the call. Tick the box and accept to run it; decline to change nothing. Your assistant app must support MCP confirmation forms; if it does not, the write is refused and nothing changes. A call too large to show in full is refused too; ask the assistant to split it into smaller calls.
Purchases
The connector never spends money without you.
Phone numbers. When the assistant buys a number, your assistant app shows a confirmation with the number, the organization and the monthly price your organization is billed. Tick the box and accept to buy it; decline to buy nothing. Your assistant app must support MCP confirmation forms; if it does not, the purchase is refused and nothing is bought.
Plans. Creating an organization, or a workspace in an organization with no
plan, needs a paid plan. The assistant first lists the plans
(list_organization_products). Then it gives you a Stripe Checkout link with
the price. Pay in your browser. When the page says Payment received, go
back to the assistant and ask it to repeat the same request — it then creates
the workspace (or the organization) once. A new workspace can join this
connection if its access rules allow it. For a new organization, first create
a workspace in it from the Gravity Rail app and wait for setup to finish.
Then reconnect and select the workspace, or its organization if the connector
allows organization-wide access. Repeating the request again does not buy a
second plan. An unpaid link expires; ask again for a new one.
When a call is refused
A refused call tells the assistant why, so it can tell you what to do:
| Reason | What to do |
|---|---|
workspace_not_in_grant | Reconnect and include the workspace or its organization |
connector_not_allowed | The organization does not allow this connector; ask an organization admin to allow it in Settings → MCP Server → AI connectors |
not_a_member | Ask a workspace admin to add you |
insufficient_scope | Your role, or the scopes you granted, lacks a permission |
step_up_required | Disconnect and reconnect to sign in with your organization's SSO again |
app_not_permitted | The connector app is restricted from that workspace |
organization_not_in_grant | Reconnect and include the organization |
missing_grant_scope | Reconnect and grant the permission the tool names |
no_active_plan | The organization has no plan: ask the assistant to list the plans and buy one through Checkout |
confirmation_unsupported | Your assistant app cannot show a confirmation; make the purchase or the change in the Gravity Rail app |
declined | You declined the confirmation; nothing was bought or changed |
confirmation_used | That confirmation was already used; ask again for a new one |
invalid_request_state | The confirmation or checkout expired, its price or terms changed, or it belongs to another request; ask again |
invalid_arguments | The call does not fit the tool's input, or it is too large to confirm in full; the message says which, so ask the assistant to fix or split it |
payment_required | Open the Checkout link in the message, pay, then repeat the request |
payment_pending | The checkout is not paid yet, or the payment went through and the plan is still being set up; finish paying or wait a moment, then repeat the request |
checkout_in_progress | The payment went through and another request is finishing it; repeat the request in a moment |
checkout_failed | The checkout could not start or be checked; or it was paid but setup did not finish — then contact support, nothing is charged again |
checkout_expired | The link expired unpaid; ask again for a new one |
checkout_mismatch | The checkout found does not belong to this request, so nothing was created; contact support@gravityrail.com and say whether you already paid |
chat_required | Run this tool from a Gravity Rail Chat in the app |
Related
- Authentication — OAuth, scopes and step-up authentication.
- MCP Server Connections — the other direction: connect an external MCP server to a Gravity Rail workspace.