Skip to content

MCP endpoints

Polaris speaks MCP (Model Context Protocol), so any MCP client (Claude, an agent framework, your own tooling) can work with a brain. There are three servers:

Server Where For Credential
Advisor https://<host>/v1/mcp Grounded, cite-then-verified answers from a published brain A key with advisor:read, or a tenant user's access token
Questions Framework https://<host>/v1/mcp/questions The Questions lifecycle: read, propose, draft, eval, approve, certify A key with at least one Questions Framework scope
Operator (stdio) a local process Polaris developers driving the whole platform POLARIS_MCP_API_KEY with mcp:invoke

The Advisor endpoint is the companion to the OpenAI-compatible endpoint: same Advisor, same API keys, a second transport.

Advisor endpoint

https://<host>/v1/mcp        # streamable-http MCP
  • Your key selects the brain. Each API key is bound to one brain, so one URL serves the brain your key belongs to. There is no path parameter.
  • <host> is wherever the capability gateway is published. Locally that's localhost:8088. The reference deployment fronts the gateway with nginx behind a Tailscale Funnel, so /v1/mcp is served at the tailnet hostname. See Edge & Tailscale.
  • It can't change the brain's knowledge. It exposes only the Advisor's four tools (below). It is not strictly read-only, though: every call writes an audit row, and when the Advisor asks a follow-up question it stores the paused route (in Redis, for 30 minutes) so your reply can resume it.
  • It is separate from the local operator server used by Polaris developers.

Auth

Send your key as a bearer token:

Authorization: Bearer sk-polaris-…

The credential is a long-lived Polaris API key (sk-polaris-…) carrying the advisor:read scope: the same key that works on /chat/completions. A tenant user's Polaris access token also works (the brain comes from the token). A platform admin's token has no single brain, so it can't connect. A key may carry other scopes too; this endpoint only needs advisor:read.

Auth failures reject the connection with an HTTP status and an OAuth-style body, {"error": "…", "error_description": "…"}:

HTTP error Meaning
401 invalid_token Missing, unknown or revoked credential.
403 insufficient_scope A valid key without the advisor:read scope.

Revocation takes effect on the next request: a revoked key stops connecting at once.

The brain needs its own OpenRouter key

A brain with no OpenRouter key of its own has no Advisor. Every answer and retrieve call then returns no answer: the envelope's guardrail is {"status": "block", "rule_id": "advisor.openrouter_key_required", "message": "This brain's Advisor needs an OpenRouter key. An admin can add one under Settings → Model providers."} and the text content says the same. The fix is a brain admin's, not your agent's: an Admin adds the key under Settings → Model providers.

Tools

Tool Input Returns
answer query: string, topic_ids?: string[], and to reply to a follow-up: route_token?: string, question_id?: string, slots?: {name: string}, reply?: string A grounded, cite-then-verified answer envelope: result, citations, confidence, guardrail, brain_version. Or, when the Advisor must ask first, needs_input (see Follow-up questions).
retrieve query: string, topic_ids?: string[] The scope-filtered source passages that ground an answer: citations, no synthesis. Use it when your agent wants the raw evidence. It never asks a follow-up.
topic_cards none The subjects this brain knows it can be asked about. Each card has an id to pass back as topic_ids.
read_wiki entity?: string Browse the published brain as articles. Omit entity for the index (categories and titles); pass a title for that article.

Follow-up questions (needs_input)

Before it answers, the Advisor works out whether a question is one of the brain's published Questions, and whether it knows the facts that Question's answer turns on (its slots). If it needs something from the person, answer returns a follow-up instead of an answer. This happens only where the brain has the advisor_question_routing flag on; otherwise answer always answers. The design is in Advisor question routing.

A follow-up sets structuredContent.needs_input, and result holds the question as plain text. needs_input.reason is one of:

  • choose_question: the Advisor isn't sure which Question is meant. candidates lists them (question_id, text, probability).
  • slots: the Advisor knows the Question (question_id) but needs facts. slots lists each one to ask: name, type, ask_text, required, and values (the allowed values; empty for free text). message may say why, for example that a required fact was answered "I don't know".

Ask the person. Don't answer for them. Then call answer again with the same query and:

  • route_token: needs_input.token, always;
  • question_id: the chosen candidate's question_id, or "none" for none of them;
  • slots: slot name → the person's own words, "I don't know" included;
  • or reply: what the person said, verbatim, if you didn't map it yourself.

slots, question_id or reply without route_token is refused with an error result, {"error": …, "code": "route_token_required", "remedy": …}. A route allows at most three replies and expires after 30 minutes. If it has expired, the Advisor says so and asks the person to ask again.

A worked round trip

1. Ask. The question could be one of two Questions:

{ "name": "answer",
  "arguments": { "query": "What notices do we owe when we decline someone?" } }
{
  "result": "Which of these do you mean?\n1. Adverse action notice for a declined consumer credit application\n2. Adverse action notice when a credit report contributed to the decline\nOr none of these.",
  "citations": [],
  "confidence": null,
  "guardrail": { "status": "pass", "rule_id": null, "message": null },
  "brain_version": "147676ad69c2…",
  "needs_input": {
    "reason": "choose_question",
    "token": "u2Q8m0kXr4V…",
    "question_id": null,
    "candidates": [
      { "question_id": "Q-dee-48", "text": "Adverse action notice for a declined consumer credit application", "probability": 0.52 },
      { "question_id": "Q-fcra-615a", "text": "Adverse action notice when a credit report contributed to the decline", "probability": 0.31 }
    ],
    "slots": [],
    "message": ""
  }
}

2. Choose. The person picks the first one:

{ "name": "answer",
  "arguments": { "query": "What notices do we owe when we decline someone?",
                 "route_token": "u2Q8m0kXr4V…", "question_id": "Q-dee-48" } }

The Advisor now needs a fact the answer turns on:

{
  "result": "Before I answer, I need to know:\n- Is the credit for personal, family or household use, or for a business? (consumer, business)",
  "citations": [],
  "confidence": null,
  "needs_input": {
    "reason": "slots",
    "token": "u2Q8m0kXr4V…",
    "question_id": "Q-dee-48",
    "candidates": [],
    "slots": [
      { "name": "credit_purpose", "type": "credit_purpose",
        "ask_text": "Is the credit for personal, family or household use, or for a business?",
        "required": true, "values": ["consumer", "business"] }
    ],
    "message": ""
  }
}

3. Fill the slot. Pass the person's own words:

{ "name": "answer",
  "arguments": { "query": "What notices do we owe when we decline someone?",
                 "route_token": "u2Q8m0kXr4V…", "slots": { "credit_purpose": "consumer" } } }

4. The answer. No needs_input; the answer ends with a note saying which facts it used:

{
  "result": "You must send the applicant an adverse action notice within 30 days … (12 CFR 1002.9(a)(1)).\n\nThis answer is based on:\n- You told me: credit purpose: consumer.",
  "citations": [ { "source_id": "12 CFR Part 1002 — Equal Credit Opportunity Act (Regulation B)", "kind": "passage", "…": "…" } ],
  "confidence": 0.82,
  "guardrail": { "status": "pass", "rule_id": null, "message": null },
  "brain_version": "147676ad69c2…"
}

The note lists the facts the person told the Advisor, defaults it assumed ("Assumed, because it wasn't known: …"), and facts it hedged over ("Not known, so the answer covers each case: …"). Facts the question itself stated need no note.

The text content mirrors this: for a follow-up it is the question plus one line telling your agent which arguments to send back.

Scoping a question to a subject

A question rarely names the citations it needs. "What notices do we owe when we turn someone down?" never says § 1002.9 or 15 U.S.C. § 1681m(a), and similarity search can't bridge that gap, because a provision's text does not repeat its own citation. Asking the index for 12 CFR 1026.4 returns citation fragments, not the rule.

A topic card closes the gap. A curator names a kind of question and the provisions its answers turn on. Passing the card's id supplies those provisions' verbatim text by exact key: the one retrieval path that can't near-miss.

Two calls. List the catalog, then scope:

cards = (await client.call_tool("topic_cards", {})).structured_content
for c in cards["topics"]:
    print(c["id"], "—", c["label"])
    print("   ", c["covers"])                     # the fact patterns, in the words people ask in

result = await client.call_tool("answer", {
    "query": "We declined an applicant because their credit score was below our threshold. "
             "What notices do we owe, and how specific must the reasons be?",
    "topic_ids": ["denying-an-application-the-notices-we-owe"],
})

Each card returns:

Field Meaning
id Pass this back as an entry in topic_ids.
label Short name: what a reader picks from a list.
covers The fact patterns it covers, written in the asker's words rather than the law's. Match your question against this, not against the label.
anchors The citation keys this subject's answers turn on.

The operator server's list_topic_cards also reports unsupportable_anchors (how many anchors the corpus can't supply). The Advisor endpoint's topic_cards doesn't.

Rules worth knowing:

  • Optional; omitting it changes nothing. An unscoped answer retrieves exactly as it always has.
  • Keep it to one or two cards. A question spanning more than two subjects is usually two questions.
  • An unknown id is ignored, not an error. A stale id from a cached catalog degrades to an unscoped answer.
  • An empty catalog is normal. topic_cards returns no topics for a brain whose curator hasn't written any, and answer behaves as before.
  • Scope is recorded. The audit row for a scoped answer carries the card ids that routed it.

Match on covers, not on label. Labels are short by design; covers is the sentence written to be matched against a real question.

The citation model

Every answer/retrieve citation is a navigable entry point back into the knowledge base, not just a label. Each entry in citations[]:

Field Meaning
source_id The cited source (a document title or entity name).
kind passage (verbatim source chunk; strongest evidence) or entity (graph/entity summary; contextual).
quote The verbatim supporting span from the source (the sentence that supports the claim, not a prefix).
locator A precise in-document locator (e.g. §1026.2) when the extractor captured one.
score Retrieval relevance of the source, 0–1.
verified / verification verification.method is entailment (LLM judge), lexical, lexical_fallback (judge errored, so unconfirmed) or unverified, plus a score.
provenance Hard provenance: source_doc_pk, doc_title, origin_url (the source document's root URL), jurisdiction.
wiki Deep links into the published Wiki: [{entity, ref}] where ref is GET /v1/brains/{brain_id}/wiki/{entity}. Follow these (or call read_wiki(entity)) to pull the full article.
concept_refs Entity names for graph traversal from the answer into the knowledge base (feed to read_wiki / retrieve).

The envelope also carries confidence (0–1, weighted by per-citation verification and retrieval strength) and guardrail (pass / disclaim / block). Treat a disclaim or low-confidence answer as "not grounded", even if prose is returned.

Two channels per result: rendered text and structured citations

answer and retrieve return both MCP content channels, so each consumer gets the right shape:

  • content (text): the answer followed by a rendered ## Sources block: one numbered entry per citation with the verbatim quote, [source](origin_url), and [wiki: entity](ref) deep links. Labels are cleaned (single-line) and de-duplicated. Interactive harnesses hand this text to a summarizing model, which often drops raw JSON; pre-rendering the sources means even a small local model can carry the provenance into its prose.
  • structuredContent: the full envelope (result, enriched citations[], confidence, guardrail, brain_version, and needs_input when set). Programmatic consumers read this directly. (The structured list is the raw pipeline output: it is not de-duplicated and labels are not cleaned; do that yourself if you render it.)

How an agent should consume citations

  • Programmatic integrations (recommended): read structuredContent, ignore the prose. Iterate citations[]: origin_url to link the evidence document, quote to quote it, wiki[].ref / read_wiki(entity) to expand a concept, concept_refs to traverse the graph, verification/score to weight or filter. Gate on confidence and guardrail.
  • Interactive harnesses (a model summarizes the tool result): the model decides what to show. A summarizing model, especially a small local one, often rewrites the answer and drops the citations. That is the client's behaviour, not a Polaris omission. Tell the agent to reproduce the ## Sources block verbatim (see the OpenCode guide for a ready-made rule), and prefer a stronger model when citations matter.

"Good answer, no citations" is almost always the model, not the endpoint. Check with a raw MCP tools/call: if the result carries citations[] and a ## Sources block, the endpoint is fine and the consuming model is dropping them.

Connect a client

Claude Code / Claude Desktop: add it as a remote HTTP MCP server:

claude mcp add --transport http polaris-advisor https://<host>/v1/mcp \
  --header "Authorization: Bearer sk-polaris-…"

Then /mcp lists polaris-advisor with its tools. Ask a question in plain language and the client calls answer. To scope a question, ask the client to call topic_cards first and pass the matching id.

Any MCP SDK (for example Python fastmcp):

from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

transport = StreamableHttpTransport(
    url="https://<host>/v1/mcp",
    headers={"Authorization": "Bearer sk-polaris-…"},
)
async with Client(transport) as client:
    tools = await client.list_tools()             # answer, retrieve, topic_cards, read_wiki
    query = "Do I need a CA lender license?"
    result = await client.call_tool("answer", {"query": query})
    env = result.structured_content                # the full envelope: read this, not prose

    while env.get("needs_input"):                  # the Advisor asks before it answers
        ni = env["needs_input"]
        print(env["result"])                       # the question, as text
        args = {"query": query, "route_token": ni["token"],
                "reply": input("> ")}              # or question_id / slots, if you mapped it
        env = (await client.call_tool("answer", args)).structured_content

    print(env["result"], "\n")
    if env["guardrail"]["status"] != "pass" or (env["confidence"] or 0) < 0.5:
        print("not well-grounded")                 # gate on grounding before trusting it
    for c in env["citations"]:
        prov = c.get("provenance") or {}
        print(f"- [{c['kind']}] {c['source_id']}  ({prov.get('origin_url')})")
        print(f"    “{c['quote']}”")

Managing keys

Keys are created and revoked exactly as for the completions endpoint: from the web app (Settings → API keys, raw key shown once), over REST (POST/GET/DELETE /v1/brains/{brain_id}/api-keys), or with the CLI (bb apikey mint|list|revoke). See Managing keys and Access, flags and scopes. One key with advisor:read works on both MCP and completions.

Questions Framework over MCP

The same Questions Framework lifecycle as the developer REST API, as MCP tools for an agent.

https://<host>/v1/mcp/questions        # streamable-http MCP

Connect

claude mcp add --transport http polaris-questions https://<host>/v1/mcp/questions \
  --header "Authorization: Bearer sk-polaris-…"
  • Keys only. The endpoint accepts a bearer sk-polaris-… key that carries at least one Questions Framework scope: questions:read, questions:write, eval:run, eval:submit, grades:submit, answer_key:approve, certification:sign_off, questions:publish or slots:write. A signed-in session's access token is not accepted.
  • Auth failures reject the connection: 401 invalid_token for a missing, unknown or revoked key (checked on every request, so a revoked key stops at once), and 403 insufficient_scope for a valid key with no Questions Framework scope. The error_description names the scopes that would do.
  • One brain. The key's brain is the only brain. Tools take an optional brain_id; omit it. Naming another brain is refused with code: brain_forbidden.
  • Flag. Every tool call is refused with code: feature_disabled unless the brain has qf_developer_api and question_store_db on. update_slots and publish_question_version also need question_slot_editing; certification_status and sign_off_certification also need questions_workspace. A platform admin turns flags on; see Access, flags and scopes.
  • Who acts. A tool call acts as the key's actor: the person who minted it over REST, or the --actor of a key minted with bb apikey mint. Every write is attributed to that actor, and Curator acts record the key's id in the audit log.

Tools

Each tool checks its own scope. A refusal is a normal tool result, {"error": "…", "code": "…", "remedy": "…"}, so your agent can branch on code. The autonomy class says what a tool may do without a person (see Autonomy classes).

Tool Scope Role Class What it does
list_questions questions:read any A0 The brain's Questions; include_drafts, topic narrow it.
get_question questions:read any A0 One Question and its Answer Keys. The rubric only for a Curator or Admin key (rubric_visible).
get_slots questions:read any A0 A Question's slots, published and draft, with each binding.
list_slot_types questions:read any A0 The slot types a binding may use; include_proposed adds the brain's proposed ones.
question_standing questions:read any A0 Standing over time, each point with its comparability tuple.
certified_bindings questions:read any A0 What is certified at a brain version (default: the published one).
certification_status questions:read any A0 Per binding: eligible, certified, reasons, and the certification_id to sign off. Needs questions_workspace.
list_eval_runs questions:read any A0 Run rows, newest first (limit 1–500). Never answer text.
get_eval_run questions:read any A0 One run and its results, with each result's id for grading.
estimate_run eval:run any A0 What run_eval would cost; allowed: false with reason if it would be refused. Free.
run_eval eval:run any A1 Live Advisor answers, judged, scored and stored. Spends the eval budget, checked before any model call.
propose_question questions:write any A2 A draft Question in the brain's store.
draft_answer_key questions:write any A2 A draft Answer Key for one binding, from expert_answer (free) or use_drafter=true (budgeted model calls). answer_key_id names it.
propose_slot_type questions:write any A2 One of the brain's own slot types, proposed until someone else approves it.
save_answer_key_draft questions:write Curator or Admin key A2 Save a whole rubric as a draft; returns validation.
submit_answers eval:submit (+ eval:run to judge) any A2 Answers your system produced; Polaris scores them.
request_approval questions:write or answer_key:approve any A2 Ask a named Curator or Admin to approve a draft.
withdraw_approval questions:write or answer_key:approve any A2 Withdraw a request this key's actor made (an Admin key may withdraw any).
update_slots slots:write Curator or Admin key A2 Edit a draft version's slots, or a published one's ask_text. dry_run available.
submit_grade grades:submit Curator or Admin key A3 The key owner's own grade on one judged criterion. The actor must be an active Curator or Admin of the brain.
approve_answer_key answer_key:approve Curator or Admin key A3 Approve a draft, so it scores and can certify. Same checks as the web app.
approve_slot_type slots:write Curator or Admin key A3 Approve a proposed slot type; never the proposer's own.
sign_off_certification certification:sign_off Curator or Admin key A3 Sign off an eligible certification. Needs questions_workspace.
publish_question_version questions:publish Curator or Admin key A3 Start version N+1 of a published Question; bindings carry over as drafts. dry_run available.

A Curator act with a Reader key is role_forbidden, whatever its scopes. A Curator act (approve, sign off, publish a version, edit slots, save a rubric, approve a slot type) also needs the key's actor to be an active Curator or Admin account of the key's brain, not an agent identity, checked at every call: actor_not_a_curator (or not_a_person) otherwise. So a key minted by a platform operator can't do Curator acts for a tenant, a key stops doing them once its actor is deactivated or demoted, and a key minted with bb apikey mint must name a real Curator's login email as --actor to do them (the CLI's default apikey@polaris is refused). withdraw_approval withdraws only a request the key's own actor made, as over REST, whatever the key's role. A tool the key lacks the scope for is scope_forbidden.

Rubric detail (the rubric, per-criterion results, penalty wording) is returned only to a Curator or Admin key that also has questions:read. Answer text is never returned, except that run_eval returns it to Curator and Admin keys.

Lifecycle order

  1. Find or propose. list_questions (or the Advisor's routing) to see what exists. If nothing covers what people ask, propose_question.
  2. Draft. list_slot_types (and propose_slot_type / approve_slot_type for a type the brain lacks), then draft_answer_key for each binding, and save_answer_key_draft to write its rubric.
  3. Approve. request_approval (a person decides in the web app), or approve_answer_key with a Curator or Admin key. Only an approved Answer Key certifies.
  4. Evaluate. estimate_run, then run_eval (ref="published" and judge=true to count toward certification). Or submit_answers for answers your own system produced; those never certify.
  5. Review. list_eval_runs, get_eval_run, question_standing; submit_grade where a person has read the answer.
  6. Certify. certification_status, then sign_off_certification with a Curator or Admin key. certified_bindings shows the result.

To change a published Question later: get_slots, then update_slots (ask text only) or publish_question_version.

How scopes map

Internally, this endpoint binds each call to an operator identity with the key's Questions Framework scopes, plus mcp:invoke, plus mcp:write when the key holds any write scope (questions:write, eval:run, eval:submit, grades:submit or a Curator scope). It never grants mcp:any-brain. You don't mint mcp:* scopes for this endpoint.

Operator (stdio) server

Polaris developers drive the full tool surface (Librarian, Scout, corpus health, the crawler, certify/publish, the Questions Framework, …) from a local stdio MCP server registered in Claude Code. It is not the customer surface above. The flow is documented in the repo cookbook: cookbooks/MCP_USER_GUIDE.md. It is local by design: never expose it remotely. It writes corpora.

Identity

There is no bearer header here: this is stdio, not HTTP, so there is no request to attach auth to. The credential arrives at process launch, and is resolved once against the same api_key table:

bb apikey mint --operator --brain-id calliope --actor you@example.com --label "claude-code"
export POLARIS_MCP_API_KEY='sk-polaris-…'

With a key, the session acts as that key's actor. A caller that passes a different actor is refused rather than silently overwritten. The key's brain becomes the default, and every audit row carries authenticated: true and the key id.

Scope Grants
mcp:invoke Use the operator toolset at all. Required: an advisor:read key does not authenticate here.
mcp:write Tools that change a corpus or a brain's Questions (autonomy class A2/A3), and the metered Questions Framework tools that spend the eval budget (question_check, question_check_compare, question_eval: scope_forbidden without it). Omit it with --read-only.
mcp:any-brain Act on a brain other than the key's own. Without it, naming another brain is refused.
questions:read The Questions Framework read tools. With a Curator or Admin role, rubric detail too.
questions:write propose_question, request_approval.
eval:run run_eval (spends the eval budget), and judging in submit_answers.
eval:submit submit_answers.
grades:submit submit_grade, as the key's own actor.
answer_key:approve approve_answer_key (the key's actor is the approver), and request_approval.
certification:sign_off, questions:publish, slots:write Curator acts on the developer REST API and the remote Questions Framework endpoint. A Curator or Admin key only.

Add Questions Framework scopes at mint time with --scope, for example bb apikey mint --operator --scope questions:read --scope eval:run …. The full scope reference is Access, flags and scopes.

Without a key the server still runs, under weaker guards: writes need an explicit brain_id and a named, non-placeholder actor. That actor is self-asserted, so every write result and audit row records authenticated: false. Questions Framework tools that spend budget, submit answers, request approvals or grade refuse an unauthenticated session (not_authenticated).

Call mcp_session before anything that writes, to see which mode you are in.

The credential is resolved once per process, so a key revoked mid-session keeps working until the server restarts.

Questions Framework tools

The operator server has list_questions, get_question, question_standing, certified_bindings, run_eval, propose_question, submit_answers, request_approval and submit_grade (from app/mcp/qf_tools.py), next to the older draft_question, approve_answer_key, question_eval, match_question, question_spec and coverage.

  • The brain comes from the key. Omit brain_id and the tool acts on the key's brain. Another brain needs mcp:any-brain, and even then a tenant key never spends another tenant's budget or writes its Questions.
  • Writes need mcp:write as well as the tool's own scope.
  • Budgets. run_eval and a judged submit_answers are checked against the brain's monthly eval budget and run cap before any model call (budget_exceeded, run_cap_exceeded). The older A1 tools (question_check, question_check_compare, question_eval) are checked the same way, take a max_cost_usd ceiling, need mcp:write on a key, and their model calls are recorded against the monthly budget.
  • Coded errors. Every failure is {"error": …, "code": …, "remedy"?: …}, for example feature_disabled, scope_forbidden, brain_forbidden, not_found, seed_unpinned, citations_missing.
  • Approval. On the operator server, request_approval only asks; the named person approves in the web app (or with their own answer_key:approve key and approve_answer_key).
  • Lifecycle with question_store_db on: propose_question → draft_question(question_id=…) → request_approval → the approver approves → run_eval → question_standing / certified_bindings.

The operator answer tool takes the same follow-up arguments as the Advisor's (route_token, question_id, slots, reply).

Autonomy classes

Tools declare what they may do without a person, enforced by app/mcp/_autonomy.py. The rule: an MCP default may never be more permissive than what the web app shows a person. Where the app renders a choice, the tool must refuse, require an explicit parameter, or disclose the default it applied.

Class Meaning Gate
A0 Read: no cost, no change none
A1 Metered: spends credits, quota or model calls a budget or ceiling; spend always returned
A2 Reversible write: changes the draft; git-revertible identity; dry_run where it applies
A3 Judgement write: records a curator's claim a named person (the key's actor, or approved_by)
A4 Irreversible: publishes or leaves the system never automated

The full tool inventory lives in the app/mcp/server.py module docstring, and a test keeps it in step with what is registered.

Limits (current)

  • The Advisor endpoint has four tools: answer, retrieve, topic_cards, read_wiki. It can't change the brain's knowledge.
  • One brain per key (the key's brain); no cross-brain access on either remote endpoint.
  • Grounded answers need a published version of the brain (read_wiki reports if there is none), and the brain's own OpenRouter key.