NATARAJA Guide

Connecting an AI Assistant Through MCP

This page is part of the NATARAJA Guide. The full Guide, covering how NATARAJA works, making and recording decisions, the protocol library, and use cases by industry, is in the User Portal (sign-in required).

In Short. For IT teams and anyone setting up an AI assistant. NATARAJA's Episteme runs as an MCP server: a standard connection that AI assistants such as Claude, ChatGPT or Gemini use to reach outside tools. Connect your assistant once, sign in with the same Google account you use for the portal, and from then on you talk to your assistant in plain English while it calls the tools for you. This page gives the address, the setup for each assistant, and the full tool reference.

For the plain-English version, read Welcome to NATARAJA first, then come back here for 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. The exact menu differs, though, 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 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 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. What it does and does not prove is set out in What You Can Rely On.
  • 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 as a summary or a simulation, following the task's instruction. On a step a person will decide, it opens its text with a Recommendation, then What Approval Means (what approving commits, what cannot be undone, what it rests on, what was not checked), and on a long text Key Points. See Making a Decision.
  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 Is 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; it 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.

Whatever your assistant submits for you is recorded as yours, and the record also names the assistant that submitted it, by the name it gave and the identity it connected with, or by that identity alone when it gave no name. The same holds when it checks a decision's freshness or chooses a winning branch for you. After a decision it submits, your Receipt names the assistant the same way; if you did not make that decision, stop it on its page and remove the assistant's access under Organisation, Agents.

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

Full Tool Reference

Tool Purpose
help Machine-facing reference for the assistant (tool names, JSON shapes, node kinds).
list_protocols {source?} Catalog of available protocols. Omit source to search everything (built-in library + registry + legacy filters). A protocol your organisation has made available only in some workspaces carries available_in, the workspaces it can run in.
get_protocol {id, source} Full normalised definition of one protocol. One of your organisation's comes with available_in beside it: "organisation", or the workspaces it can run in.
validate_protocol Checks a protocol design holds together structurally before it's saved.
create_protocol Designs and registers a brand-new protocol from a description (the "topology designer" pipeline: build → validate → fix → save).
create_protocol_legacy Legacy/back-compat path for protocol creation.
get_protocol_genealogy Shows which protocols a given one was derived from / has spawned.
start_run {protocol_id, context, on_behalf_of} Begins a governed run. context satisfies the protocol's data obligations. A start in a workspace where the protocol is not available is refused, naming the workspaces it can run in.
get_next_task {run_id} All currently-ready tasks (AI or human) for the run.
submit_task {run_id, node_id, output} Submit the assistant's completed work for a task.
submit_review {run_id, node_id, decision, amended_output?} Human review verdict on a gated node: approve / reject / amend.
submit_human {run_id, node_id, kind, value} Human-supplied input (kind: "input") or human-authored step (kind: "author").
get_run_status {run_id} Progress summary of a run.
get_run_view {run_id} A fuller structured view of a run's current state (nodes, edges, statuses).
get_run_attention {run_id} What's currently waiting on a human, with human-time estimates: the same steps the Portal lists under the Decisions page's Now tab.
get_run_entropy {run_id} The run's rework: the share of steps that did not land first time (steps redone, plus outputs a reviewer rejected).
get_trace {run_id} The full hash-chained event log - every submission, timestamp, and any recorded deviation.
check_freshness Re-checks a completed run against the current values of its sources: the ones you supply, and any bound files. Flags it stale if an input has drifted, lists what it compared, and records who asked. A re-check with nothing to compare is refused.
branch_run Forks a run at a step to explore an alternative path without discarding the original. The branch keeps the approvals of the steps it inherits and must leave a step to redo; it is billed only for the steps done in it. A branch of a withdrawn version is refused.
merge_branches Reconciles two branched runs back together.
create_data_nodes Registers new data nodes (evidence/conclusions) outside the normal task-submission flow, when needed.
project_to_studio Returns the link where something is read: a run's own page, with its graph, or a protocol in Read. It makes nothing.

When a step reads a spreadsheet with charts declared, get_next_task and get_run_view also return charts: each figure with how it was worked out, the points behind each chart, and the file they came from. Your assistant is told to show them to you before asking for a decision. The fields are in Technical Concepts.

Recurring Decisions

These set a protocol to start by itself. See Recurring Decisions for what happens each time and when one does not start. A newly added tool appears to an assistant only after it reconnects.

Tool Purpose
set_schedule {protocol_id, context, cadence, when_unchanged?, worked_by?, version?, workspace_id?} Sets one. cadence is {every: "day"|"week"|"month", at: "09:00", time_zone: "Asia/Bangkok", weekday?, day_of_month?}. worked_by is "nataraja_model", the default, or "own_agent" for your assistant to do it. Pass schedule_id to change one you set. Needs the Set Recurring Decisions permission, and the person it acts for is emailed.
list_schedules {include_ended?} Those you set or could stop, each with who does its AI steps, its next time, what happened last, and the run it last started.
change_schedule {schedule_id, action} pause, resume, end or run_now. On one your assistant does, run_now is how your assistant starts it.

With worked_by: "nataraja_model", the default, each run one starts has its agent tasks worked by NATARAJA's model, not your assistant. Your assistant can still relay a gate on it, with its charts, through get_next_task.

With worked_by: "own_agent", nothing starts at its time. You are emailed a prompt for your assistant instead, and the same prompt is under Copy Prompt on the Act tab. Given it, your assistant may first bring newer data for the files the decision reads, with list_files and upload_file, and tells you what it added and where it came from. Then it starts the decision with change_schedule and run_now, works its AI steps with get_next_task and submit_task, and brings you the steps that are yours. See When Your AI Assistant Does the Work.

New data reaches a decision when a new file is bound where it runs, before it starts: on the Assets page, or by your assistant with the tools below.

Files in Assets

These do what you can do on the Assets page, as you and with your permissions there. See Adding Files Through an Agent. A newly added tool appears to an assistant only after it reconnects.

Tool Purpose
list_files {workspace_id?} The workspace's files with their status and fingerprint, what each stands behind, and which evidence still needs a file, with what it reads.
upload_file {name, content | content_base64, bind?} Adds a file sent in the call: text as content, a PDF, workbook or Word file as content_base64. For a larger file, send name, size and content_type without content to get a private upload address, upload to it with the headers given, then call finish_upload. With bind, the file is bound once it passes its checks.
finish_upload {file_id, bind?} After uploading to the address: has the file checked, and binds it when asked.
bind_file {file_id, protocol_id, node_id, file_name?, sheet_name?, header_row?} Binds a ready file to a protocol's evidence. file_name names one of several documents; a workbook needs its sheet and heading row.

Each file is checked and charged exactly as one you add yourself, and Assets marks it Through an Agent. The size limits are on Welcome. Removing a file or a binding stays on the Assets page.

Choreography: Dances

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

Tool Purpose
dance_start {question, epochs?, protocol_id?} Starts a Dance on a question. Pass protocol_id to seed it from an existing protocol instead of a blank draft - use the version's doc id (my-protocol__v0.1.0), not the bare registry id.
dance_status {dance_id} Progress: status, epoch, current Dance Score.
dance_final {dance_id} The Chosen Way - the settled method, in plain prose.
dance_move {dance_id, verb, node_id, note?} Queue your Move (expand/branch/link/revise/merge/retire) as the next epoch. On a resting Dance this wakes it.
dance_continue {dance_id, add_epochs?, direction?, phase?} Wakes a finished Dance for more epochs, web, scores and memory intact. direction is a standing instruction for the session; phase is diverge, consolidate or deepen. A Dance that rested on convergence refuses until one of them, or a wake Move, changes.
dance_stop {dance_id} Halts the loop at the next epoch boundary.
dance_list Dances you own or that are shared with you.
dance_export {dance_id, name?, visibility?} Registers the Chosen Way as a new protocol, ready to run, and links to it in Read in Episteme. Returns unverified_schemas - evidence shapes written at export time that need your review.
dance_rehearse {dance_id} Runs the Chosen Way as a governed run worked by NATARAJA's model and reads the conclusion against the Frame. Poll dance_status for rehearsal.score and rehearsal.objection; the objection is the natural next direction.

Access and Organisation

Tool Purpose
grant_role / revoke_role Give or remove someone's authority on a run, Dance, workspace or organisation.
list_bindings Who currently holds what authority.
define_role Define a custom role as a set of capabilities.
list_roles / get_capabilities The available roles and what each can do.
get_iam_log The hash-chained governance log: every grant, revoke and role change.
delegate_agent / revoke_agent / list_agent_grants Control what an AI agent may do on your behalf - an agent can never exceed your own authority.
get_billing_status Decision-credit balance and current price card.

How this powers the Portal: get_run_attention reports the same waiting steps the Portal lists under the Decisions page's Now tab; list_protocols (registry source) is what populates the Protocols tab of Assets, and completed runs populate the Books. The Portal is a read/act surface over the same underlying state these tools read and write, so 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, so 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 as a diagram?" Assistant: (calls project_to_studio and gives you a link to the run's own page, with its graph beside the reading, step by step.)

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 Use

What You Want What to Say
Use an existing process "Can you review/check/analyze this for me?"
See what's available "What kinds of processes do you have available?"
Build something new "I want a process that does X, then Y, then Z."
Run it "Run it on this: [your input]"
See it visually "Show me that as a diagram."
See how it was reached "Can I see the trace / how you got this?"
Check it still holds "Is that conclusion still fresh?"
Explore an alternative "What if we branched from here and tried Y instead?"

Protocol Names

Your assistant can find a protocol from a plain request, but when you want to be exact, these are the technical names of the library's protocols. What each is for is in The Protocol Library.

Protocol Technical Name
Dual-Pass Review dual-pass-review
Organisational Intelligence org-int
Recommendation Memo recommendation-memo
Engagement Go / No-Go engagement-go-no-go
Discovery Synthesis discovery-synthesis
Assumption Stress-Test assumption-stress-test
Deliverable Clearance Gate deliverable-clearance
Multi-Stakeholder Decision multi-stakeholder-decision
Independence Attestation independence-attestation
Sealed-Bid RFQ Award sealed-rfq
EU AI Act High-Risk Inventory and Classification eu-ai-act-inventory
Command Decision (the Decide play) command-decision
Command Delegation (the Delegate play) command-delegation
Command Approval (the Approve play) command-approval
Command Exception (the Exception play) command-exception
Command Review (the Review play) command-review
Retrieve and Extract from a Web Page source-web-page
Produce Values from a Described Model source-model-values