MCP server

Onepin runs a remote Model Context Protocol server at https://mcp.onepin.ai. Connect it once and your agent — Claude Code, Claude Desktop, Cursor, ChatGPT — gets nineteen tools that browse the voice catalog, author and validate workflows, price a run, start it, and hand the audio back as a link you can play.

It acts on the same workspace the console and the REST API do, with exactly the permissions your workspace role already gives you. It doesn’t replace the CLI — what it adds is a one-command connection with nothing to install, and a confirmation step the server enforces before anything is spent or overwritten.

The CLI’s agent skill is the other way to hand Onepin to an agent, and the two coexist. The skill has your agent run the local CLI under your API key; this runs the tools server-side under your sign-in. Which to pick.

Sign in — there is no API key

MCP authenticates by OAuth only. You don’t mint, paste, or store anything: your client sends you to a normal Onepin sign-in, you approve it once, and it holds a token that refreshes itself. The connector acts as you.

Revoke the connection from your account settings at any time; the token stops working within a minute.

Connect

Paste the bare hostname. There is no path and no trailing slash — MCP has its own subdomain, and the OAuth resource identifier has to equal what you typed, character for character. A stray /mcp is a discovery failure your client then caches for about five minutes.

Claude Code

claude mcp add --transport http onepin https://mcp.onepin.ai --scope user

Then run /mcp, pick onepin, and choose Authenticate — Claude Code never opens a browser by itself. --scope user makes the server available in every project; the default (local) registers it only for the directory you ran the command in.

Claude Desktop and claude.ai

Settings → Connectors → Add custom connector, paste https://mcp.onepin.ai, and sign in when the browser opens.

Cursor

Add it to ~/.cursor/mcp.json (or .cursor/mcp.json for a single project):

{
  "mcpServers": {
    "onepin": {
      "url": "https://mcp.onepin.ai"
    }
  }
}

Anything else

The server speaks streamable HTTP and advertises OAuth 2.1 at https://mcp.onepin.ai/.well-known/oauth-protected-resource. Any client that can discover an authorization server connects with the URL alone.

Verify

Ask for something small — “list my Onepin workflows”. If you belong to more than one workspace, the first tool call says so and lists them: list_workspaces, then select_workspace. The choice is remembered for 30 days and across reconnects.

Tools

Workspace

Workflows

Voices

Runs

Destructive means it can destroy or overwrite work you already have. run_workflow spends credits irreversibly, set_workflow_voice is a last-write-wins overwrite of a voice map an open canvas may be editing, and update_workflow is that same overwrite over the whole graph — the definition it replaces is not versioned anywhere you can get it back from. Creating a workflow is additive, so it isn’t marked.

Nothing is spent or overwritten on the first call

run_workflow, create_workflow, and update_workflow do nothing the first time they are called. Each returns requires_confirmation: true carrying what you need to judge it, and acts only on a second call with confirm=true:

• A run comes back with workflow_name, workflow_summary, expected_credits, max_credits, and current_balance — plus estimated_overage_cents when it would bill past your plan allowance.
• A create comes back with name and workflow_summary, and not_included when the graph leaves something out: no translator, no normalizer, no quality check, or a check whose failing lines are discarded. If the workspace already holds something that looks like what you asked for, those candidates come back instead, and force=true is how you decline the offer.
• An edit adds replaces — the graph that is there now — content_changes for any node text the edit would rewrite, and an edit_token the confirming call must carry. That token is signed over the workflow, the definition, and the graph as it stood, so a workflow someone else changed while you were reading is refused rather than silently overwritten.

Two tools also require a token from a read-only call, so that what you approved is what happens: create_workflow needs the validation_token from validate_workflow_definition, and run_workflow needs the run_token from estimate_run. The run token is single-use and is refused if the workflow moved after you priced it, or if the price rose above the ceiling you approved. Both expire after 10 minutes, and a refusal always means nothing happened — the remedy is one more read-only call.

Audio comes back as links

Every audio URL this server hands back — find_voices and preview_voice samples, get_run_outputs’ per-line files — is a plain presigned file: no auth header, no page to log into, good for about an hour.

What that looks like depends on your client. One with a shell (Claude Code, Cursor) fetches the URL and plays it with whatever your machine has. A host that supports MCP Apps (Claude Desktop, claude.ai, Cursor, VS Code) renders an inline player — one row per sample, one per line for a run, nothing autoplaying, and past 20 lines it points at download_run instead. Anything else gets a titled link on its own line rather than a raw presigned URL.

Nothing plays unasked. preview_voice(search=…) searches and hands back a shortlist with played: false, leaving the choice to you; pass catalog_voice_id when you’ve already named a voice and it plays straight away.

Authoring a workflow through an agent

get_node_info() with no argument returns three things: the node catalog, definition_shape — the envelope, where nodes and edges live under graph rather than at the top level — and pipeline_choices, the stages that are a decision rather than a default (a translator, a normalizer, a quality check) with what skipping each one does instead.

Two things no config_schema will tell you:

• Don’t compute positions. create_workflow lays the whole graph out with the product’s own canvas layout, so send {"x": 0, "y": 0} for every node. On an update only the nodes your edit touched are re-placed — cards someone dragged stay where they put them.
• Wire a validator’s fail port, or know why you aren’t. Connect it to the generator’s lines port and a failing line is regenerated, bounded by that validator’s max_retries. Leaving it unconnected is legal and means the opposite: failing lines are discarded, and the run completes with a shorter export than the script. See How validators work.

Editing a workflow you already have is a round trip:

get_workflow(include_definition=true) → edit → validate_workflow_definition
  → update_workflow()                      # writes nothing; returns replaces + an edit_token
  → update_workflow(confirm=true, edit_token=…)

Existing runs are untouched by an edit — hearing the difference means estimate_run and run_workflow again, which charges credits again.

Troubleshooting