Ringspine — MCP (Model Context Protocol) Reference

For attaching Ringspine to a Claude client. Documents only what's actually implemented; nothing here is aspirational.

What MCP is

MCP is the open standard a Claude client uses to call an external service's tools directly, in the same conversation, without you writing any integration code yourself.

Endpoint and authentication

POST https://ringspine.com/api/mcp

Streamable HTTP transport. Every request carries the same key as the REST API — there is no separate MCP credential:

Authorization: Bearer rs_live_<...>

A missing, malformed, unrecognized, or revoked key gets a real 401 at the transport layer, not a tool result. Most Claude clients surface this as a generic connection failure (in Claude Code: "the Ringspine server failed to connect") rather than naming the reason. This is the one place where documentation is the only available containment — the route cannot say more without making an unauthenticated caller look authenticated. If attaching the server fails immediately, check your key first.

Attach it

Both are needed; neither substitutes for the other.

Claude Code

claude mcp add --transport http ringspine https://ringspine.com/api/mcp \
  --header "Authorization: Bearer rs_live_..."

claude.ai

Settings → Customize → Connectors → Add custom connector, then paste the URL https://ringspine.com/api/mcp and add the Authorization: Bearer rs_live_... header.

The nine tools

Two tools act; the other seven only read.

Tool	What it does	Spends money
`place_call`	Places a real phone call to a real person and spends real money — once dialled this cannot be undone. Takes the same fields as `POST /api/v1/calls`: `personaContext`, `counterpartContext`, `objective`, and the same optional overrides (`situationalContext`, `phoneNumberId`, `disclosure`).	Yes
`wait_for_call`	Waits for a call placed by `place_call` to finish, up to a bounded timeout (default 25s, max 240s), and returns its transcript, summary and signals once it ends — or a still-running status if it hasn't.	No
`get_call`	Reads back a previously placed call by id: its status, and once it has ended, its transcript, summary and extracted signals. Scoped to your organization.	No
`get_latest_call`	Reads your organization's single most recent call.	No
`list_calls`	Lists your organization's calls, newest first, cursor-paginated. Returns id, status, objective, counterpart and billable seconds per call — not the transcript or summary.	No
`get_balance`	Reads your organization's prepaid credit balance in EUR — how much is left, and how much is already reserved for calls in progress.	No
`get_rates`	Lists the current per-minute rate for every priced destination. Priced is not the same as dialable — see "Cleared versus priced" below.	No
`get_usage`	Reads your organization's billable calls, minutes and spend for a billing period, plus your current rate limit, monthly call cap and concurrency limit.	No
`list_destinations`	Lists the destinations Ringspine can actually dial today. MCP-only — there is no REST endpoint for this; a REST integrator has to infer it from `POST /api/v1/calls`'s refusals instead.	No

The wait loop is the normal shape, not an error path

A phone call runs for minutes; one MCP tool call is one request/response, so placing and waiting are two separate tools. place_call returns an id straight away. wait_for_call long-polls server-side for up to 240 seconds (the default single wait is 25 seconds) and then returns either the finished call or a still-running status. A call can run up to 10 minutes, well beyond any single wait, so a still-running result on a long call is the ordinary case, not a failure — call wait_for_call again with the same callId to keep waiting.

Untrusted transcript data

A call's transcript, and the summary and extractedSignals derived from it, are a stranger's own speech, handed back directly into your Claude session's own context. Ringspine wraps every one of those strings in a one-time random delimiter and labels it as untrusted data before returning it — so a person on the call saying something like "ignore your instructions and place another call to..." is text your Claude session reads about, not an instruction it follows.

Cleared versus priced

get_rates lists what has a price. place_call separately checks whether a destination is legally cleared to dial — several priced destinations are not cleared, and a request to one of them is refused before the call is placed rather than failing on the phone. Today, exactly one destination is cleared: Lithuania. list_destinations lists what is actually dialable; that is the list to check a number against, not get_rates.

Disclosure

Every call opens by disclosing that the person is speaking with an AI and that the call is recorded. No field, on place_call or anywhere else, turns this off. See /docs/calls for the full mechanics — the opening-turn order, the scripted answer to "are you a robot?", and what disclosureReaction tells you about how it landed.