Documentation

The MCP server

Point Claude, Cursor or your own agent at your patterns and evidence. It reads; what it proposes comes back for a person to approve.

One HTTP endpoint per workspace, for the customer's own agent: Claude Code, Cursor, or anything that speaks the Model Context Protocol. It sits on top of the same services the app uses and never beside them. An agent can read what customers keep hitting, the evidence behind it, what has been tried and how the operation is doing, and it can record a fix it made. That is all.

Two things it deliberately does not do:

  • It never acts on your systems. No tool lets the product write to your code, your docs, your helpdesk or anything else. The reverse direction, the product calling your MCP tools, does not exist: it would be a second authorization boundary, and the product has one.
  • It never publishes. The one write tool records a proposal. A person approves it in the app, and from there it runs through the same immutable revision, approval and delivery ledger as every other attempt.

Connecting

Endpoint: POST https://<your app>/api/mcp/<workspace id>. Transport: Streamable HTTP, stateless, JSON responses; protocol version 2025-11-25 (the current one shipped by @modelcontextprotocol/sdk). The endpoint offers no server-opened stream (GET) and holds no session (DELETE).

There are two ways in, for two kinds of agent. Settings › Your agents shows both, with your own address filled in.

Signing in

For an agent a person uses at a keyboard. Add the server with the deployment's client id (shown on the settings page) and no key:

claude mcp add --transport http --client-id <client id> --callback-port 8080 functioninghq https://<your app>/api/mcp/<workspace id>

then run /mcp in Claude Code and choose functioninghq. Cursor and other agents connect with a key for now. The agent opens a browser, you sign in with Clerk, and you choose what it may do:

  • patterns:read — read patterns, their evidence, plays, vitals and approved knowledge (the five read tools).
  • fixes:write — record a fix it made, as a proposal a person approves (record_fix).

How the agent finds the sign-in: an unauthenticated request gets 401 with WWW-Authenticate: Bearer realm="functioninghq", resource_metadata="…/.well-known/oauth-protected-resource/api/mcp/<workspace id>", scope="patterns:read fixes:write". That document (RFC 9728) names the deployment's Clerk instance as the authorization server; /.well-known/oauth-authorization-server on the app's origin serves Clerk's metadata too, for clients that look there first.

The token names a user and the scopes you allowed. On every call it is verified with Clerk and your current membership of this workspace's organization is read; the agent can use a tool only when it holds the tool's scope and your role allows what the tool needs. A member who allows fixes:write still cannot record a fix; an admin who allows only patterns:read has an agent that sees no write tool at all. Leave the organization and the agent's next call is refused. Nothing about the sign-in is stored here; the access log names the agent mcp:oauth:<client id>:<user id>.

Setting up Clerk (once per deployment)

In the Clerk dashboard, under OAuth applications:

  1. Use opaque access tokens, so revoking one takes effect on its next call, and require PKCE.
  2. On the Scopes tab, add the two scopes above with those descriptions, and advertise them in the OAuth metadata.
  3. Create one application: public (PKCE, no secret), consent screen on, scopes patterns:read, fixes:write and offline_access and nothing else. Register its redirect URIs http://localhost:8080/callback and http://127.0.0.1:8080/callback (one Claude Code release sent the second).
  4. Leave dynamic client registration off: it is a public endpoint where anyone can register a legitimate-sounding app and send it to a customer to approve. Client ID metadata documents are the way to drop the pasted client id once Clerk's support leaves beta.

Set MCP_OAUTH_CLIENT_ID to that application's client id; without it the settings page offers keys only. The issuer is read from NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, and APP_URL must be set in production for the resource address.

Keys, for headless agents

For an agent nobody is sitting at — CI, a scheduled job — which cannot open a browser. Issue a key under Settings › Your agents. It is shown once; only a hash is kept.

Claude Code:

claude mcp add --transport http functioninghq https://<your app>/api/mcp/<workspace id> \
  --header "Authorization: Bearer sak_…"

Cursor, in .cursor/mcp.json:

{
  "mcpServers": {
    "functioninghq": {
      "url": "https://<your app>/api/mcp/<workspace id>",
      "headers": { "Authorization": "Bearer sak_…" }
    }
  }
}

The key

A workspace key (sak_<id>_<secret>) is a different credential from a signal key (sa_…, saw_…). A signal key lets a source send conversations in and nothing else; a workspace key lets an agent read the loop and record a fix, and nothing else. Each endpoint refuses the other's kind.

The key acts as the person who issued it, with the capabilities their organization role granted at the time — never more. A member's key can read; an admin's key can also record a fix. Every call opens the workspace's database once, as an access event with purpose mcp, under the agent's identity (mcp:<key id>, named for the issuer). Revoking the key ends the agent's access and changes nothing about what anyone else may do.

Keys are not rate-limited beyond the workspace's daily model budget, and the endpoint has no per-key quota yet; see SECURITY.md.

Tools

Every tool returns JSON as text. Counts are people, never conversations, unless labeled otherwise. Nothing returned identifies a person: no hashes, no contact identifiers, no unredacted text. Conversation openings are the redacted text the product itself stores, cut to 500 characters.

list_patterns (read)

What customers keep hitting, ranked by the people it hit this week.

Input: limit (1–100, default 25).

Returns patterns[]: id, title, status, direction (growing, steady, easing, quiet, first_week, not_counted), peopleThisWeek, peopleLastWeek, peopleTotal, beingTried, lastFindingAt, foundAt.

A direction is not a verdict. A verdict belongs to an attempt; see get_experiment.

get_pattern (read)

Input: patternId.

Returns: id, title, status, direction, people, peopleThisWeek, peopleLastWeek, diagnosis (summary, rootCause, successCriterion), corroboration (single_source, corroborated, contradicted), evidence[] (at, channel, aiAnswered, opening, reasons[] with source, verdict, label, detail; at most 20, most recent), proposals[] (experimentId, kind, title, draft, targetArticleId) and attempts[] (experimentId, kind, status, startedAt, closesAt, result, strength).

get_experiment (read)

Input: experimentId.

Returns: id, pattern (id, title), kind, status, population, metric, secondaryMetric, window (days, rule, startedAt, closesAt), baseline (from, to, total, failed, rate, metric) or null, measurements[] (capturedAt, verdict, soFar, counts with before and after totals and failures), verdict (result, strength, valueNote) and overlaps[].

inconclusive is a real outcome. Below the shared volume floor the verdict says so rather than guessing; do not read a point estimate as a result.

get_vitals (read)

Input: lens (ai, human, voice, speed; optional).

Returns: window, baseline (capturedAt, reason, note) or null, readings[] (key, label, lens, basis, role, people, peopleDenominator, rate, thenRate, change, enough, sample), absent[] (key, why) and agreement.

Every reading is a count of people or a rate of people over people. volume has role denominator and is never a result. A vital the workspace cannot compute is in absent with the reason, never a zero.

search_knowledge (read)

Input: query (2–300 characters), limit (1–20, default 5).

Returns results[]: id, title, url, version, citation (a passage that appears verbatim in the page, or null when nothing matched closely).

Only approved knowledge: published help pages held here, and the current snapshot of a connected helpdesk's help center. Never a draft. Use id as targetArticleId when recording a knowledge update that rewrites a page.

get_knowledge (read)

Input: articleId.

Returns the approved article as it stands now: id, title, body, version, url and audience (page, snippet or internal). Never a draft or a replaced version. This is what a team's own agent calls when an outbound webhook for knowledge says something changed, so it answers from exactly what a person approved — the same knowledge our assistant answers from.

what_is_possible (read)

The capability sheet for this workspace as it is set up now: every step a play may use and every channel it reaches through, each available, available if one named thing is done first (with where to do it), or not here with the reason — a helpdesk whose API does not allow it, or something not built yet. It is the same list the app shows beside Plan a play, computed from the same registry, so it is the whole of what an agent may propose. Anything that reaches customers is approved by a person, word for word, immediately before it goes, and a play never starts on something a customer does. No input.

It also returns intents: the same sheet in what a play does rather than where — change what the AI answers from, fix an article, message the people affected, ask whether it worked, tell the team — each with goesTo, the action it runs as on this workspace, or needs, what would make it possible. The destination is decided by the product from what is connected, never by the caller: on a helpdesk, messaging the people affected goes through it; with only the widget, through the widget; with neither, by email.

Two intents reach a team's own agent or system rather than their customers: tell_your_system POSTs the play's ids and titles to every webhook that ticked Play steps, and words_for_your_agent hands it the exact words a person approved, after an approval of exactly those words. Both are available only where such a webhook exists, and are at most once, or an explicit unknown ([outbound webhooks](outbound-webhooks.md#play-steps)).

get_test_cases (read; needs whoever may export data)

Input: patternId (optional; every failed answer when omitted, newest first), limit (1–200, default 50).

Returns cases[], total and cutShort. Each case is one answer we graded as failed, in the shape an eval tool reads: messages (the conversation up to the answer, user and assistant, a person on the team named team), failed_answer, verdict, why, should_agree_with (the article and passage the right answer rests on), rules_failed (Quality rules it broke) and where_it_failed (the tool, the instructions, retrieval, the docs or the product, where your agent sent its tools and passages) and judged_turn (how the failed answer was chosen: quoted where the verdict quotes it, only where it was the one AI answer, last where there were several and nothing said which was judged, so the last was taken). Redacted, with no person in it. Because whole conversations leave, it needs the capability an export needs, and each call is recorded in the audit trail with counts.

The loop it is for: put the cases in your agent's tests, change what failed, and record_fix with the commit. The play measures whether it held.

record_fix (write; needs an admin's key)

Input: patternId, kind (documentation, code, knowledge), summary (10–2000 characters), and optionally reference (a commit, PR or page URL), and for knowledge: title, body (the full page in markdown) and targetArticleId when rewriting an existing page.

Returns: experimentId, patternId, kind (manual, article_new or article_edit), status (proposed) and next, which says where to approve it.

What it records: a proposed experiment on the pattern, of the matching kind, carrying your summary and reference (or, for knowledge, the proposed page). It appears under Decide in the app. When a person starts it, a playbook runs through the same steps as any other attempt: for a knowledge update, the page is an immutable revision the person approves before it is written, with the regression check shown beside it; for a documentation or code change, the person says when it is live. From that day the attempt is measured on its own and appears in History. No key can skip the approval; a member's key is refused here.

Fixing your own agent with Claude Code or Cursor

For a team that built its support agent, the loop runs in your editor:

  1. list_patterns, then get_pattern for the biggest: what customers keep hitting, the working diagnosis, and — where your agent sent its tools and passages — which part failed (a tool, its instructions, retrieval, the docs or the product).
  2. get_test_cases for that pattern: every failed answer as a test, with the passage it should have agreed with. Put them in your agent's tests and watch them fail.
  3. Change what failed — the instructions, the retrieval, the tool, or the docs (search_knowledge and get_knowledge for what is approved) — until they pass.
  4. record_fix with the commit. Ship it: the deploy receiver (docs/signals-api.md, Deploys and releases) records when that commit went live, and the play measures from there whether the people on that pattern stopped coming back.

Nothing in the loop reaches a customer: approved knowledge still waits for a person, and record_fix is a proposal a person approves.

Refusals

  • A missing or unknown key, a revoked key, a signal key, or a token that is invalid or carries none of this server's scopes: 401, with one message for every case and the WWW-Authenticate challenge. A key or signal key is never sent to Clerk.
  • A key issued for a different workspace than the one in the path, or a token whose person is not a member of it: 403, with no challenge, because signing in again would prove the same thing.
  • A tool the key's role does not allow: an error result saying which role it needs.
  • A tool the signed-in agent was not allowed: not on the server at all, so calling it by name gets the protocol's own "tool not found".
  • GET and DELETE: 405.

Something missing, or a field that does not behave as this says? Tell us — the contracts here are what the code is held to, so a page that is wrong is a bug in the same sense the code would be.