Diaphora MCP Server

The Diaphora MCP server is the remote Model Context Protocol endpoint for the Diaphora platform. Use a client that supports Streamable HTTP and the pre-registered OAuth setup below. Authentication and tool discovery are setup steps; verify a successful tool call before relying on the connection.

Authentication

Diaphora Core uses OAuth 2.1 (authorization code + PKCE) with pre-registered clients. Create a client on the Clients page in the Diaphora app to get a client_id (and optional secret), then supply it to your MCP client. Diaphora doesn't support Dynamic Client Registration, so a client can't register itself on first connect.

Redirect URIs

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

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.

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.

frags_run_plan

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

frags_fetch_results

Retrieve the results of a previous plan 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:

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.

Connecting

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

Claude apps (web / desktop / mobile) and Cowork

Add Diaphora as a custom connector in Settings → Connectors, using the URL https://mcp.diaphora.ai/mcp. Under Advanced settings, enter the OAuth client ID and client secret from your Clients page, then approve the OAuth consent screen. The redirect URI these surfaces use, https://claude.ai/api/mcp/auth_callback, must be registered on that client (see Redirect URIs).

Claude Code (CLI)

Add the server with the HTTP transport, passing the client ID from your Clients page (see Authentication).

claude mcp add --transport http \
  --client-id <your-client-id> \
  --client-secret \
  --callback-port 8080 \
  diaphora-core https://mcp.diaphora.ai/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:

Select diaphora-core → 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

Client compatibility depends on transport, OAuth client authentication, callback handling, and the negotiated MCP protocol revision. Point it at https://mcp.diaphora.ai/mcp, configure the client ID and secret from your Clients page, and complete the browser-based authorization flow. A client that can only connect through Dynamic Client Registration won't work, because Diaphora doesn't support it.

Verify the connection

After authentication, ask your client to call frags_search_plans with no arguments. A successful call returns the plans you can access (which may be an empty list). Then use frags_load_plan to inspect one plan before running it with its required parameters. Listing the tool catalog alone does not confirm that tool calls work.

The MCP surface supports finding, inspecting, and running existing plans and fetching results. Create or edit plans and manage connections and schedules in the app; these actions are not exposed by the four tools documented here.

If a client cannot supply the authentication method required by your registered OAuth client, the connection cannot complete through that configuration. Check client support before registering credentials. Do not assume an unlisted client is supported.

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." Check the two settings the CLI depends on. Its redirect URI, http://localhost:8080/callback, must be registered on the client alongside the Claude apps' URI, and the client's token_endpoint_auth_method must be client_secret_basic, which is what Claude Code uses.

Tool discovery succeeds, but a tool call fails schema validation. This can indicate that the server response does not match the MCP protocol revision negotiated with the client. Record the client version, negotiated protocol revision, tool name, and exact validation error and share them with support. Reauthenticating or changing plan inputs does not resolve a malformed protocol response.

Reference

• Endpoint: https://mcp.diaphora.ai/mcp
• Client credentials: https://app.diaphora.ai/user/clients
• 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