Using Episteme Through MCP

Episteme runs as an MCP server that your AI assistant (e.g., Claude Code, Claude Desktop, or any MCP-compatible client) connects to directly. You never call these tools yourself - you talk to your assistant in plain English, and it calls the tools on your behalf. This page explains what's happening behind the scenes, in enough detail that you can direct the conversation with confidence.

If you just want the "talk to it like a person" version with zero jargon, read Reference & FAQ first, then come back here when you want the mechanics.

Connecting your AI assistant

Episteme's MCP server is hosted at:

https://mcp.episteme.nataraja.io/mcp

Sign in with the same Google account you use for the Portal (OAuth 2.1) - this links what your assistant does over MCP to the same identity you see runs and conclusions under in the Portal. An API key is also supported for clients that can't complete an interactive sign-in.

Where to add this depends on your client. The general shape is the same everywhere - find the setting for adding a custom MCP server / connector and paste the URL above - but the exact menu differs and changes as these products evolve, so treat the steps below as a starting point rather than gospel:

• Claude (claude.ai, Claude Desktop): Settings → Connectors → Add custom connector, then paste the URL and complete the Google sign-in when prompted.
• Claude Code: add it as a project- or user-scoped MCP server, e.g. claude mcp add --transport http episteme https://mcp.episteme.nataraja.io/mcp (or the equivalent entry in .mcp.json).
• ChatGPT: on plans that support custom connectors, look under Settings → Connectors (sometimes labelled "Apps & Connectors") for an option to add a custom MCP server by URL.
• Grok: look for MCP or tool/connector settings in whichever Grok surface you're using (the web app, a coding client, or the API) - MCP support and its exact settings location vary by product and are changing quickly.
• Antigravity (and similar MCP-aware IDEs/agents): look for an "MCP Servers" section in settings and add the URL as an HTTP-based server.
• Gemini Enterprise: add a custom MCP server connector. It asks for the server URL above, plus an authorization URL, a token URL and a client ID, which your administrator can obtain from us. Leave the client secret empty and see the note below.

If your client's settings don't match any of the above, search its docs for "MCP" or "custom connector" - any MCP-compatible client can reach Episteme the same way, through the same URL.

One setting to watch for. Some clients offer a "client secret" field and an option like "HTTP Basic Auth" for sending it. Episteme does not use a client secret: it uses the modern proof-key method instead, which is safer because there is no shared password to leak. So leave the secret empty and turn that option OFF. If it is left on, the client has nothing to put in the password field and the sign-in fails at the last step, usually with a message about a token rather than about the setting that caused it.

What the MCP server actually is

• A protocol runtime: it owns the topology (the graph structure) of whatever process you're running. Your assistant is the model that fills in the content of each step - it does not control the order.
• Protocols come from two sources: a built-in library (e.g. dual-pass-review) and the platform's protocol store, which also holds legacy Studio filters, normalised on the fly.
• Every run is recorded as an append-only, hash-chained event log (the trace) - this is what later shows up as the run's record in the Portal (see the trace note in Foundational Concepts for exactly what this does and doesn't prove).
• Enforcement is real, not cosmetic: get_next_task only reveals a task once its dependencies are genuinely complete, and submit_task rejects (and logs) any attempt to submit out of order or with empty output.

The core loop (what your assistant does)

list_protocols  →  start_run  →  loop{ get_next_task → do the work → submit_task }  →  report

1. list_protocols - searches every source at once (the built-in library and the platform's protocol store) to find something that already fits your request.
2. start_run { protocol_id, context, on_behalf_of } - begins a governed run, feeding in whatever input you gave (a document, a question, data). on_behalf_of records your identity as the human principal behind the run.
3. get_next_task { run_id } - returns every task that's currently ready to be worked (parallel tasks may all be ready at once; the assistant can do them in any order). Each task comes with its instruction and its ordered, labelled inputs.
4. The assistant does the actual work - genuinely, not a summary or a simulation - following the task's instruction.
5. submit_task { run_id, node_id, output } - submits the result. The runtime validates it and advances the graph, unlocking whatever depends on it.
6. Repeat 3 to 5 until the run status is completed.
7. The assistant reports the sink outputs (the final conclusion(s)) and the run_id back to you.

When it's not the assistant's turn

Some tasks are yours, not the AI's:

• awaiting_review (with review_tasks) - a produced output needs a human to approve it before downstream work continues. Your assistant will surface this to you and call submit_review with your decision: approve, reject (with your rationale - reopens the node), or amend (supplying your edited version as amended_output).
• awaiting_input (with input_tasks) - a step's output must come from you directly, not be generated by the AI. Your assistant relays the request and calls submit_human (kind: "input" for a data source only a human can supply, kind: "author" for a step only a human can perform) with what you tell it.

A run can also be aborted server-side by a review timeout or by exceeding a rejection-retry cap - both of these are recorded as deviations in the trace, not silently swallowed.

Full tool reference

Choreography (Dances)

These author a method rather than executing one. See Choreography for what a Dance is and when to use one.

Access and organisation

How this powers the Portal: get_run_attention is the same data source behind the Portal's Review Inbox; list_protocols (registry source) is what populates the Registry page, and completed runs populate Conclusions. The Portal is a read/act surface over the same underlying state these tools read and write - nothing you see in one is out of sync with the other.

The exact tool surface can grow over time - if your assistant has access to the Episteme MCP server, its own help tool output is always the up-to-date technical reference. This table reflects the tools available as of this writing.

Example conversations

Using something that already exists:

You: "Can you review this business plan for me - both supportively and critically?" Assistant: (calls list_protocols, finds dual-pass-review fits, calls start_run, works through the empathetic pass, the hostile pass, then the synthesis - each one genuinely gated on the last - and reports back the synthesis plus the run id.)

Nothing existing fits - design something new:

You: "I want a process where you assess this from a business angle, a risk angle, and a governance angle, then bring those together into one final decision." Assistant: (calls create_protocol, which builds the topology, validates it, fixes anything broken, and saves it - you never see a broken intermediate version.) "I've created a process called business-risk-governance-review. It's ready to use whenever you'd like."

Running it:

You: "Run it on this: [attach/paste input]" Assistant: (calls start_run, loops get_next_task/submit_task until completed, reports the final answer and the run id.)

Viewing it visually:

You: "Can you show that in the studio?" Assistant: (calls project_to_studio and gives you a link - a read-only diagram you can click through, node by node.)

Checking a decision still holds:

You: "Is that decision from last month still good?" Assistant: (calls check_freshness on the run; if a source drifted, tells you it's stale and offers to re-run.)

Phrases you can just say