Diaphora MCP Server | Diaphora Docs | Diaphora

Diaphora MCP Server

The Diaphora MCP server is the remote Model Context Protocol endpoint for the Diaphora platform. Point any MCP-compatible client — Claude Code, the Claude apps, Cursor, your own agent — at it, authenticate once over OAuth, and you MCP tool access to the Diaphora Platform.

Authentication

Diaphora Core uses OAuth 2.1 (authorization code + PKCE). There are two ways a client obtains an OAuth client identity:

Dynamic Client Registration (DCR) — the client registers itself with the authorization server on first connect. This is what the Claude apps do, and what Claude Code does when you don't pass --client-id. Nothing to pre-configure.
Pre-registered client — Diaphora issues you a client_id (and optional secret) up front, which you supply to the client. Use this when DCR is disabled or you need a stable client identity.

Redirect URIs

The authorization server matches the redirect URI exactly. Register the URI(s) your client uses:

Client	Redirect URI to register
Claude Code (CLI) with `--callback-port 8080`	`http://localhost:8080/callback`
Claude apps / web / desktop / Cowork	`https://claude.ai/api/mcp/auth_callback`

Notes for whoever administers the OAuth server:

The CLI callback is localhost (not 127.0.0.1), plain http, path /callback, with the port included. If you want to accept any CLI port, register the port-less http://localhost/callback as well and allow port-agnostic matching.
The token endpoint must accept the client-authentication method the client uses. Claude Code authenticates with client_secret_basic; if your OAuth client is registered for client_secret_post, the token exchange fails with "unsupported authentication method." Set the client's token_endpoint_auth_method to match.

See Troubleshooting for the exact error strings and fixes.

Tool reference

Frags engine

These four tools are the generic interface to every plan in your org.

`frags_search_plans`

Search or list available plans.

Parameter	Type	Required	Description
`search`	string	no	Partial plan name to match. Omit entirely to list all plans.

Returns an array of plans, each with its id, name, description, parameters, visibility, namespace, labels (required tools/collections), and signature (if promoted to a named tool).

`frags_load_plan`

Load a plan's full definition — parameters, required tools, sessions, and output schema.

Parameter	Type	Required	Description
`plan_id`	string	yes	The plan's UUID.

`frags_run_plan`

Execute a plan by ID and return its results (or a results handle).

Parameter	Type	Required	Description
`plan_id`	string	yes	The plan's UUID.
`parameters`	object (string→string)	no	Runtime parameter values the plan declares.

`frags_fetch_results`

Retrieve the results of a previous plan run.

Parameter	Type	Required	Description
`results_id`	string	yes	The results ID returned by a run.

Typical flow:frags_search_plans to find a plan → frags_load_plan to inspect its parameters → frags_run_plan with those parameters → frags_fetch_results if the run is asynchronous.

Visibility and namespaces

Plans are scoped, so you only see and run what's relevant to you:

Visibility	Who can see / run it
`user`	Only the creator
`namespace`	Members of the plan's namespace (e.g. a team like `barndoor`)
`organization`	Everyone in the organization

frags_search_plans returns plans across the scopes available to your authenticated identity. A plan's namespace groups related work; its labels (e.g. mcp:Barndoor-Slack, collection:proof_of_funds_postgres) declare the tools and data collections it depends on — useful for knowing what a plan will touch before you run it.

Building your own plans

The tools on this server run plans that already exist in your org. To author new plans — sessions, output schemas, tool calls, and promoting a plan to a named tool with a signature — head to the Guides, which walk through the Frags plan format end to end.

Claude apps (web / desktop / mobile) and Cowork

Add Diaphora as a custom connector in Settings → Connectors, using the URL https://mcp.diaphora.io/mcp. The hosted Claude surfaces perform Dynamic Client Registration automatically, so there are no flags to set — you just approve the OAuth consent screen. (The redirect URI these surfaces use is https://claude.ai/api/mcp/auth_callback; it's already handled on Diaphora's side.)

Connecting

The server speaks Streamable HTTP and authenticates with OAuth 2.1 (authorization code flow with PKCE). Below are the common clients.

Claude Code (CLI)

Add the server with the HTTP transport. If Diaphora issued you a pre-registered OAuth client, pass its client ID; otherwise omit it and Claude Code will register itself dynamically (see Authentication).

ShellCopy

claude mcp add --transport http \
  --client-id <your-client-id> \
  --client-secret \
  --callback-port 8080 \
  diaphora-core https://mcp.diaphora.io/mcp

A few things that trip people up:

--client-secret is a bare flag — it does not take the secret inline. Claude Code prompts for it (masked) or reads it from the MCP_CLIENT_SECRET environment variable. Passing --client-secret 'value' makes the CLI treat your secret as the server name and fail with Invalid name ....
--callback-port fixes the local OAuth redirect port so it can be pre-registered on the server side (see below). Without it, Claude Code uses an ephemeral port that won't match a fixed allowlist.

Then complete the OAuth handshake from inside a session:

/mcp

Select diaphora → Authenticate. A browser opens for consent; on success you'll be redirected to http://localhost:8080/callback and the status flips to authenticated. On recent CLI versions you can also run claude mcp login diaphora-core from the shell.

Other MCP clients

Any client that supports remote MCP over Streamable HTTP with OAuth 2.1 can connect. Point it at https://mcp.diaphora.io/mcp and complete the browser-based authorization flow. If your client supports Dynamic Client Registration it needs no pre-configuration; otherwise register a client with Diaphora and configure its ID/secret.

Troubleshooting

Invalid name <secret>. Names can only contain letters, numbers, hyphens, and underscores. You passed the secret inline to --client-secret. It's a bare flag — drop the value and let it prompt, or set MCP_CLIENT_SECRET.

redirect_uri does not match any of the OAuth 2.0 Client's pre-registered redirect urls The client's callback isn't on the allowlist. Register the exact URI — http://localhost:8080/callback for the CLI with --callback-port 8080, https://claude.ai/api/mcp/auth_callback for the Claude apps. Match localhost vs 127.0.0.1, scheme, path, and port exactly.

The OAuth 2.0 Client supports 'client_secret_post', but method 'client_secret_basic' was requested The token-endpoint auth method doesn't match. Claude Code uses client_secret_basic; set the OAuth client's token_endpoint_auth_method to client_secret_basic. This is a server-side client-registration setting, not something the claude mcp add flags control.

"Works in the Claude app but not in Claude Code." The apps use Dynamic Client Registration (they register their own client with a matching auth method), while a CLI configured with a hand-registered --client-id uses that fixed client. Either align that client's token_endpoint_auth_method to client_secret_basic, or drop --client-id so the CLI does DCR too (if the server allows it).

Reference

Endpoint: https://mcp.diaphora.io/mcp
Frags engine tools: frags_search_plans, frags_load_plan, frags_run_plan, frags_fetch_results
Named agents (current): sales_audit, prep_call_analysis, voice_of_customer, altai
Model Context Protocol: https://modelcontextprotocol.io