Skip to main content

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";
  • read and write — run a tool that tool_search found;
  • invite_org_member, list_organization_products, create_organization, create_workspace, search_phone_numbers, purchase_phone_number and 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:

ReasonWhat to do
workspace_not_in_grantReconnect and include the workspace or its organization
connector_not_allowedThe organization does not allow this connector; ask an organization admin to allow it in Settings → MCP Server → AI connectors
not_a_memberAsk a workspace admin to add you
insufficient_scopeYour role, or the scopes you granted, lacks a permission
step_up_requiredDisconnect and reconnect to sign in with your organization's SSO again
app_not_permittedThe connector app is restricted from that workspace
organization_not_in_grantReconnect and include the organization
missing_grant_scopeReconnect and grant the permission the tool names
no_active_planThe organization has no plan: ask the assistant to list the plans and buy one through Checkout
confirmation_unsupportedYour assistant app cannot show a confirmation; make the purchase or the change in the Gravity Rail app
declinedYou declined the confirmation; nothing was bought or changed
confirmation_usedThat confirmation was already used; ask again for a new one
invalid_request_stateThe confirmation or checkout expired, its price or terms changed, or it belongs to another request; ask again
invalid_argumentsThe 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_requiredOpen the Checkout link in the message, pay, then repeat the request
payment_pendingThe 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_progressThe payment went through and another request is finishing it; repeat the request in a moment
checkout_failedThe checkout could not start or be checked; or it was paid but setup did not finish — then contact support, nothing is charged again
checkout_expiredThe link expired unpaid; ask again for a new one
checkout_mismatchThe checkout found does not belong to this request, so nothing was created; contact support@gravityrail.com and say whether you already paid
chat_requiredRun this tool from a Gravity Rail Chat in the app