Runic
MCP

Connect Claude to your flows over MCP

Runic runs an MCP server with 19 tools, seven prompts, resources and a change stream; connect from claude.ai with a click, from Claude Code with one command, read-only or read and write.

Try it free →Read the docs

What it is

The MCP server lives at https://runicflow.ai/api/mcp. It speaks stateless JSON-RPC 2.0 over Streamable HTTP (protocol 2025-06-18): every POST carries a Bearer token, nothing is kept between calls, and a GET with Accept: text/event-stream opens a change stream. Any client that supports the HTTP transport can use it: claude.ai custom connectors, Claude Code, Claude Desktop, MCP Inspector, or a script of your own. The server introduces itself as “runic” with instructions telling the model to read get_syntax_guide before writing, lint_text before write_document, and render_document to show a diagram.

The 19 tools fall into five groups. Reading: list_documents, read_document, search_documents, get_syntax_guide. Checking without saving: lint_text, audit_document. Writing: write_document, create_document, rename_document, restore_version, share_document — the five that need write scope. Understanding the workspace: workspace_graph, references, diff_versions, list_versions. Drawing and exporting: render_document, export_markdown, export_build_package, export_docs. Seven prompts — gap-analysis, review-before-merge, flows-to-tests, code-to-sequence, code-to-system, draft-process, build-spec — package Runic’s own workflows for the client’s model, and every document is a resource at runic://doc/<id> next to runic://legend/process, runic://legend/sequence and runic://graph.

Two ways in: OAuth or a personal token

claude.ai and other remote clients sign in with OAuth: paste the endpoint as a custom connector, Runic’s consent screen opens, you press Allow, and the client receives a one-hour access token it renews on its own with a 30-day refresh token — nothing is pasted. The connection appears under Settings → Claude & MCP as “OAuth · Claude” with its scope and expiry; Revoke ends it at once. The claude.ai walkthrough has its own page.

Claude Code and header-based clients use a personal token. Settings → Claude & MCP → Create a token shows it once; tick Read-only first and Claude can read, search, lint and render but not change anything. Tokens start with runic_, are stored as a SHA-256 hash, never expire, and are revoked with one click. You can hold five personal tokens; OAuth connections are counted separately, up to 20. On every call the server hashes the header value, looks it up, stamps last_used_at and resolves the owner; a missing, revoked or expired token gets a 401 with a WWW-Authenticate header pointing at the OAuth discovery document, which is how an OAuth-capable client knows it can register and sign you in. A suspended account resolves to nothing, and suspension deletes its tokens.

What a write looks like

read_document returns “# <name> (<kind>, id <id>)”, the text, and the reading legend for that kind, so the model gets the rules next to the content. write_document replaces the full text: before writing, if the stored text differs, the previous text is snapshotted — unthrottled — as a version labelled “Before Claude edit (MCP)”, and the reply reports parse errors (0-based lines) and audit findings for processes and sequences alike, so the model can fix and write again. restore_version snapshots the current text as “Before Claude restore (MCP)” the same way before replacing it. Both rows carry an MCP chip in Version history and evict with the 50-row cap like automatic snapshots, unlike the versions you name. create_document takes a kind, a name and optional text; rename_document changes only the name — .do and .go lines in other documents are rewritten only when you rename inside the app. share_document creates, or returns, the read-only /s/ link and the /embed/ URL.

A write is visible in the app. Every MCP write stamps the document as edited via MCP; when a tab comes back to the foreground with nothing unsaved it re-fetches the list, and if Claude changed something while you were away a toast says “Claude edited ‘<name>’ over MCP while you were away.” with a History pill that opens that document’s versions.

Beyond read and write

lint_text parses and audits text that is not saved yet, so a model can draft, lint, fix and only then write. audit_document runs the same on a stored document — processes and sequence diagrams both. render_document draws a stored document, or unsaved text with a kind, as a PNG (the default, shown inline by clients that render images) or as SVG, in the editor’s light theme with JetBrains Mono, with direction ttb or ltr for processes, a compact flag for narrow cards without icons, and a scale of 1 to 3 (default 2); if the native rasterizer is missing the reply says so and returns the SVG instead. workspace_graph returns every .do/.go edge with its line, the orphans, the unresolved targets and the reference cycles; references answers what depends on one document and what it depends on. diff_versions compares two snapshots by id, or the keywords latest and current (its defaults), and lists the findings the change fixed or introduced before the line diff. export_markdown returns the same file the Export menu downloads; export_build_package returns the whole Build Package — CLAUDE.md, KICKOFF.md, docs/spec.md, docs/plan.md, docs/design-brief.md, docs/decisions.md, the Runic rules file, docs/flows/*.runic and docs/sequences/*.runic, plus .claude/settings.json when a test command is known — with the ten quality tells as a lint; pass only: “lint” to get just the score, or paths to fetch chosen files whole, because a package over about 20k tokens is truncated per file to fit a client’s result cap.

The change stream polls your documents every 4 seconds and emits notifications/resources/updated for each document whose text moved — with a via field saying mcp or app — and notifications/resources/list_changed when one was created or deleted, with a ping every 15 seconds. Each connection closes after 50 seconds; the client reconnects with Last-Event-ID (a millisecond timestamp) and misses nothing. A GET without the Accept header answers 405 with a sentence explaining both uses of the endpoint.

Why it matters

Your flows stop being a place you visit and become something your tools can read. Ask Claude Code to search every process for a term, audit the onboarding flow, or draft a refund process and hand back the share link, all without opening the editor; ask claude.ai to render the flow it just changed. Because the documents are text and the server returns parse errors and audit findings on every write, the model corrects itself instead of leaving broken documents behind. And because the server calls no model — the tools are deterministic parsing, auditing, layout and rasterizing, the prompts are text templates — MCP use never touches Runic’s AI budget or your stored API key.

Limits

Per account: 600 calls an hour (“Rate limit reached.”), 120 stream opens an hour, at most 20 messages in one batch (413 “Batch too large (max 20).”), 10 token creations an hour, five personal tokens and 20 OAuth connections. Document text is cut at 100,000 characters and names at 200; search_documents returns the first 60 hits; a prompt argument is read up to 4,000 characters. create_document shares the app’s 60-new-documents-an-hour bucket and, once billing is switched on, the free plan’s cap of 10 processes and 10 sequence diagrams. The server lists the documents your account created, including inside a team; a teammate’s documents are not reachable through your token, and a team document where you are a viewer refuses writes with “Write failed — the document may be read-only for this account.” A read-only token answers every write tool with “This token is read-only (scope: read). Create a token with write access under Settings → Claude & MCP.”

How to use it

  1. Open Settings → Claude & MCP
    Click your avatar (the initial at the top right), choose Settings, then “Claude & MCP” in the left nav. The section lists your active tokens and connections with their scope, creation and last-used dates.
  2. From claude.ai: add a custom connector
    In claude.ai open Settings → Connectors → Add custom connector, paste https://runicflow.ai/api/mcp, sign in to Runic when asked and press Allow. No token is needed; the row appears as “OAuth · Claude”.
  3. From Claude Code: create a token
    Click “Create a token” (tick “Read-only” first if Claude should not change anything). A green panel shows the token once — “copy it now, it will not be shown again” — and the command to run.
  4. Run the one-liner
    claude mcp add --transport http runic https://runicflow.ai/api/mcp --header "Authorization: Bearer <token>". The server appears as “runic” and its prompts as /mcp__runic__<name> slash commands.
  5. Other clients
    A client that takes a URL and headers uses the endpoint https://runicflow.ai/api/mcp with Authorization: Bearer <token>; a client that speaks the MCP authorization spec discovers the OAuth sign-in from the endpoint on its own.
  6. Let Claude read the legend, then revoke when done
    The server’s instructions ask the model to call get_syntax_guide before writing; ask it to list your documents first. “Revoke” on any row ends that token or connection — the next call gets a 401.

Commands & shortcuts

claude mcp add --transport http runic https://runicflow.ai/api/mcp --header "Authorization: Bearer <token>"one-line Claude Code setup
list_documentsevery process and sequence with id, name, kind and line count — processes first
read_document <document>full text of one document by id or exact name, plus the reading legend for its kind
search_documents <query>case-insensitive substring search; name matches and matching lines with 0-based line numbers, first 60 hits
get_syntax_guide [kind]the process legend, the sequence legend, or both (the default)
lint_text <kind> <text>parse + audit unsaved text — the draft → lint → write loop
audit_document <document>parse and audit a stored process or sequence without writing
write_document <document> <text> — write scopereplace the complete text; a “Before Claude edit (MCP)” snapshot first, then the parse and audit report
create_document <kind> <name> [text] — write scopenew process or sequence; the report follows when text was given
rename_document <document> <name> — write scopechange the name only; references elsewhere are not rewritten
restore_version <document> <version_id> — write scopereplace the text with a snapshot after a “Before Claude restore (MCP)” snapshot of the current text
share_document <document> — write scopecreate or return the read-only /s/ link and /embed/ URL
list_versions <document>snapshot id, timestamp, line count, label and an mcp marker, newest first, up to 200 rows
diff_versions <document> [from] [to]findings fixed or introduced plus the line diff; from defaults to latest, to defaults to current
workspace_graph · references <document>edges with lines, orphans, unresolved targets, cycles · what depends on one document and what it depends on
render_document <document | kind + text> [format png|svg] [direction ttb|ltr] [compact] [scale 1–3]the diagram as an image or SVG, server-rendered with the editor’s layout engines
export_markdown <document>the same Markdown file the Export menu downloads, legend included
export_build_package [project] [documents] [spec] [only: lint] [paths]the Build Package as files with the ten-tell lint; lint only, or chosen files whole, past ~20k tokens
promptsgap-analysis · review-before-merge · flows-to-tests (document) · code-to-sequence (feature, name) · code-to-system (lens, scope, language) · draft-process (brief) · build-spec (documents)
resourcesrunic://doc/<id> · runic://legend/process · runic://legend/sequence · runic://graph; GET + Accept: text/event-stream for changes

Tips

  • Create one token per client so you can revoke one without touching the others; personal tokens are named “Claude” or “Claude (read-only)”, so tell them apart by scope and by the created and last-used dates.
  • Give a reviewer a read-only token. Every write tool then answers with the read-only sentence instead of changing anything, and prompts, resources and the change stream still work.
  • Documents resolve by id or exact name. Ask Claude to call list_documents first so it works from real names; on a name tie a process wins over a sequence.
  • write_document is a full replace. Ask for a read first, then a targeted rewrite, and check the parse and audit report that comes back — the pre-edit snapshot is there if it went wrong.
  • Ask Claude to render_document after a write: a PNG in the conversation is the fastest review of what it just did.
  • Over MCP the model of your Claude plan does the work; Runic’s $5 monthly AI budget and your stored API key are untouched.

Questions

Does the token expire?

A personal token never expires: it stays valid until you click Revoke, delete your account, or the account is suspended. An OAuth access token lasts one hour and is renewed by the client with a 30-day refresh token that restarts on every refresh; Revoke ends both at once.

Can Claude reach my team’s documents?

The server lists documents your own account created, including ones you created inside a team. Documents created by other team members are not visible through your token, and a team document where you are a viewer refuses writes.

Does a write over MCP show up in version history?

Yes. Before write_document changes a document, and before restore_version replaces it, the current text is snapshotted with no throttle as “Before Claude edit (MCP)” or “Before Claude restore (MCP)”, marked with an MCP chip in History and with an mcp marker in list_versions.

Why does GET /api/mcp return 405?

Because the request had no Accept: text/event-stream header. POST JSON-RPC messages to the endpoint, or GET with that header to open the change stream; the DELETE clients use to close a session returns 200 and tears nothing down.

Does MCP use cost me anything on Runic’s side?

No. Nothing under the MCP server calls a model. Your Claude Code, claude.ai or Desktop subscription runs the tools and prompts; Runic’s AI budget, your bring-your-own key and the cost ledger see none of it.