MCP Server

gori ships a built-in MCP (Model Context Protocol) server. Instead of embedding a chat window in the TUI, gori exposes its project over a clean tool interface so any MCP-capable agent (Claude, Codex, Grok, and others) can read your traffic and drive the tools.

gori mcp

The server speaks JSON-RPC 2.0 over stdio: STDOUT carries the protocol, STDERR carries logs. Tool results include both backward-compatible text and MCP structuredContent when the payload is JSON.

Choosing a Project

cd /path/to/my-repository && gori mcp # path-binds this Git workspace to its own gori project
gori mcp --project my-engagement   # serve a named project's database
gori mcp --db /path/to/project.db  # serve a specific database file
gori mcp --use-active-project      # explicitly serve the active TUI/MRU project
gori mcp --no-project              # force unbound even inside a Git workspace

With no explicit selector, gori discovers the nearest Git root and binds its canonical path to an isolated project. The binding prevents two repositories with the same directory name from sharing a database.

Outside a Git workspace (the common case when an AI client spawns MCP from a home or app directory), the server starts unbound: the MCP handshake and tool list succeed immediately, but traffic tools (list_history, send_request, …) return NO_PROJECT until the agent calls list_projects, create_project (auto-binds when unbound), or switch_project. Unbound mode never silently opens the active TUI or MRU project; that requires the explicit --use-active-project opt-in (or --project / --db / GORI_MCP_PROJECT / GORI_MCP_DB).

A few tool families never need a project and work unbound: project management (project_info, list_projects, create_project, switch_project, delete_project, export_project, import_project, diff_projects), the pure-compute helpers (decode, jwt_*, cookie_*, sequence_analyze), the query-language reference (ql_reference, ql_explain), the global wordlist catalog (list_wordlists, get_wordlist, save_wordlist, rename_wordlist, delete_wordlist), and the ad-hoc OAST listener (oast_presets, oast_payload, oast_start, oast_stop, oast_poll). Everything else, including the persisted oast_resume / oast_release, answers NO_PROJECT until one is bound.

If the selected project cannot be opened (a database that is missing, corrupt, or unreadable, a project name that no longer exists), the server still completes the handshake and starts unbound rather than exiting. The reason is written to stderr, repeated in the handshake instructions, returned with every NO_PROJECT tool error, and reported as bind_error by project_info, so the agent can call list_projects and switch_project to recover without a restart.

Call project_info before using data. It reports bound, the selected project, database path, workspace root, selection source, and the project description: the operator's note on what this engagement is for, which create_project stores and this call reads back.

The project named in instructions is the one bound at the handshake. That text is sent once and nothing pushes an update to it, so after a switch_project it still describes the binding as it was then while every later call reads and writes the new project. project_info is the live answer. switch_project (and create_project when it auto-binds) returns the same correction in their result, alongside previous_project, the binding they moved off.

Read-Only Mode

By default the server also exposes action tools that send live requests and write issues. To expose only the read tools (safe for handing a project to an untrusted agent), start it read-only:

gori mcp --read-only

A read-only server also keeps no writer. It never writes the project it serves and runs no background indexing, because SQLite allows a single writer, and a second gori holding that slot for nothing but its own bookkeeping is what makes it contend with the TUI capturing into the same project. The one exception is a database written by an older gori, which is migrated on open because this build cannot read it otherwise.

A default (actions-on) server still has a writer (send_request and create_issue need one), but it does not idle-index. Free-text search drains the backlog on demand; the capturing TUI is the process that keeps the index current in the background.

One consequence is worth knowing: free-text search (body:) reads an index that is built off the capture commit, and a read-only server cannot build it. If flows are still waiting to be indexed, such a query is refused with FTS_BACKLOG rather than answered from a partial index; open the project in gori, or drop --read-only, to drain it.

Permissions from Preferences

--read-only is decided where the agent is installed. For a switch you flip from gori itself, Settings → AI → MCP permissions has one row per group of tools, each on, ask or off, all on by default:

Reading the capture is not a group: the read tools and operator_messages / reply_to_operator are always served. A tool in a group that is off is absent from tools/list and refused with TOOL_DISABLED if called anyway, and the handshake instructions tell the agent which groups you turned off. The switches compose with --read-only and --tools: a tool is served only when all three allow it. They are read when a gori mcp process starts, so an agent already running keeps the tools it was given until its server is started again; a settings file that start cannot read turns every group off rather than on.

Ask keeps a group's tools listed and puts each call in front of you first. The call returns APPROVAL_PENDING with an approval_id at once, and gori shows an approval card on the ask: chip, built from gori's own facts: the tool and, for a send, the host and port it dials. Answer it there. Allow once lets that exact call (same tool and arguments) run on its retry, Always (this server) lets the group through until that gori mcp process exits, and Deny refuses the retry with TOOL_DISABLED. A send from send_request, send_websocket, ws_session_*, ws_inject, race_requests, timing_requests, fuzz_start, mine_start, sequence_start, minimize_repeater, cache_deception_check or grpc_reflect is asked about per host instead, with Always this host and Always host:port; those grants are saved in the project, survive a restart, and are dropped when the project is imported from an archive, and for a host whenever a host override for it is added, changed or removed, since the grant named the server that name dialled. The sandbox, and an exclude rule for a sweep, still stop a granted host. Pollers and stops (fuzz_status, stop_job, oast_poll, …) never ask. The answer reaches the agent as an operator message with in_reply_to set to the approval id, and the agent retries the same call; nothing waits, so every other call keeps working meanwhile. An unanswered card expires after 30 minutes and the next retry asks again. Ask needs a bound project the server can write to; without one, the call is refused with TOOL_DISABLED.

The groups are capabilities, not destinations. With Intercept control on, an agent can still forward a held request it has edited, and those bytes reach the target even with Send traffic off. Turn both off to keep an agent's bytes away from the target. Likewise, Change scope & sandbox off stops an agent moving the fence, not stepping over it: a send with allow_unscoped:true still reaches a target the rules do not cover (the sandbox still blocks it), so turn off Send traffic too if that matters, or set Change scope & sandbox to ask: the waiver then waits for your approval of the host instead of waiving by itself. Two other switches can change where a request lands: host overrides (Edit project data) remap an in-scope hostname to another address, and Manage projects lets the agent bind a project with a different scope and sandbox.

Choosing Which Tools Are Exposed

By default gori mcp advertises every tool, so an agent can reach the whole workbench without a restart. The price is context: a client loads the entire catalogue into the model's context before the first question and keeps it for the session. Every start logs how many tools it serves and how large tools/list is. For a client with a tight context budget, start from a profile:

Tokens are bytes ÷ 4, a rough rule for JSON; your client's tokenizer has the final word.

Which one to start from. The agent eval in eval/ measures the profiles against each other on capture-analysis tasks: read, filter, count and correlate captured flows. Across Sonnet and Haiku the profile did not measurably change whether a task was answered, but it set the cost: the full catalogue took a median 3.5–4× the input tokens of @minimal for the same answer (1.7–5.5× by task; --read-only about 1.6×, @recon about 1.4×). The catalogue is re-sent on every turn, so the absolute gap grows with every call, and a smaller model makes more of them. For an agent that reads and maps a capture, start from --tools=@recon --read-only, or @minimal when it only reads History and flows; @recon alone adds a replay and issue and note writes. Keep the full catalogue for an agent that drives the workbench (fuzz, discover, authorize, sequence), which the eval does not measure yet.

A profile is a fixed list of names, not a glob, so a later gori that adds a list_* tool does not quietly grow @recon. Both keep switch_project and create_project, so they work on an unbound start, even on a machine with no project yet.

@recon serves probe_scan passive only: its active, allow_unscoped, unsafe, aggressive and insecure arguments are left out of the schema, and a call that sets one is refused with TOOL_DISABLED. Name the tool in the spec (--tools='@recon,probe_scan') to serve it whole.

--tools takes a comma-separated list of tool names, * globs and @profiles, applied left to right; a term prefixed with - subtracts:

gori mcp --tools=@recon                                          # a profile
gori mcp --tools='@minimal,send_request'                         # a profile plus one tool
gori mcp --tools='@recon,-send_request'                          # a profile minus one
gori mcp --tools='-fuzz_*,-mine_*,-discover_*,-sequence_*'       # everything but the async workbench

Because the tools are named in prefix families (list_*, intercept_*, fuzz_*, oast_*), a glob selects a group. A spec that starts with a subtraction begins from every tool, so it keeps working when a later gori adds one.

Tools that document a required follow-up (async job status/results/stop, flow paging) bring those companions into the catalogue automatically, transitively. If a later subtraction excludes a required companion while keeping its parent, startup refuses the conflicting filter; add the companion again after the subtraction or remove the parent. Conditional live-intercept readers honor explicit exclusions: if intercept_get is hidden but intercept_list is served, get_current_context points to its preview and metadata while noting that full detail is unavailable. If both are hidden, it says the held item cannot be read through this server instead of restoring either reader.

A narrow spec can also leave the server with no way to pick a project. If it starts unbound (outside a Git workspace, with --no-project, or because the configured database would not open) and the spec keeps neither switch_project nor create_project, nothing the agent calls can bind one. list_projects does not count: it lists projects and binds none of them. gori warns at startup, and the NO_PROJECT errors say the same thing instead of naming tools that are not there. Keep switch_project in the spec, or pass --project/--db.

The opposite need, a server that must stay on one project, is --pin-project. It withholds every tool that rebinds the server or reads another project (list_projects, switch_project, create_project, delete_project, import_project, export_project, diff_projects), on top of whatever --tools and --read-only already narrow; --read-only alone leaves switch_project working. It is not a filesystem fence: a tool that reads a path you give it (import_flows, a wordlist file) can still read any file the server can. A pinned start that ends up with no project (--no-project, outside a workspace, or a database that will not open) aborts instead of serving a server nothing can repair.

A pattern or profile that matches nothing aborts at startup with a suggestion (--tools: "list_hisotry" matches no tool — did you mean list_history?) rather than quietly serving a smaller set, because a server missing a tool looks exactly like a gori that never had the feature. Tools left out are absent from tools/list and refused if called anyway, naming the flag that hid them. --tools composes with --read-only, and like every other flag it is written into the command when you pass it alongside --install-*.

Seeing an Agent From the TUI

While an MCP server is bound to a project, gori shows it. In the project picker the project's row carries an mcp mark (mcp×2 for more than one), and once the project is open a clickable mcp:<client> chip appears on the top bar. Click it, or run app.agents from the command palette, to open a card listing every attached agent: its name, version, pid, when it connected, and whether it is read-only. The name comes from the client's own clientInfo handshake; a server started with --read-only shows as read-only there. A row disappears on its own the moment its process exits, so the chip and card always reflect what is attached right now.

Installing Into an Agent

gori can write the MCP configuration for common clients for you:

Pi requires an MCP adapter such as pi-mcp-adapter. Install it with pi install npm:pi-mcp-adapter, then restart Pi. --install-pi writes the MCP server configuration.

Every client except Claude Desktop and Hermes keeps its config in the same place on macOS, Linux and Windows. Hermes reads $HERMES_HOME when it is set, and otherwise ~/.hermes (%LOCALAPPDATA%\hermes on Windows). Claude Desktop follows Electron's app-data directory instead: ~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows, and $XDG_CONFIG_HOME/Claude/ (defaulting to ~/.config/Claude/) on Linux. gori reads that variable, so a Nix or home-manager session that moves it is followed too.

The exception is a Flatpak Claude Desktop: it reads XDG_CONFIG_HOME from inside its own sandbox (~/.var/app/<app-id>/config/Claude/), which the host shell running gori cannot see. There gori writes ~/.config/Claude/claude_desktop_config.json and prints that path; copy it into the app's sandbox directory yourself. Every install command prints the file it wrote, so check that line against where your build actually reads.

gori mcp --install-claude-code
gori mcp --install-codex
gori mcp --install-grok
gori mcp --install-hermes
gori mcp --install-pi
gori mcp --install-claude-code --install-codex  # several clients in one run

Codex and Grok use TOML with an [mcp_servers.gori] table, and Hermes YAML with an mcp_servers: entry, rather than JSON. Restart the client (or re-open the session) after installing so it reloads MCP servers. Existing config files are updated in place: other servers, tables and comments are preserved, the file's permissions are kept, and the replacement is atomic so an interrupted install can never truncate it. gori edits the TOML and YAML files as text rather than re-emitting them from a parse tree, so the documentation you keep around your own settings survives the install (a JSON config, which holds no comments, is parsed and written back with its other keys kept); a config it cannot splice safely is reported and left alone rather than rewritten.

If a client starts MCP outside your repository directory, the server starts unbound and the agent can pick or create a project over tools. To pin a fixed engagement at install time instead, pass a selector, for example gori mcp --project my-engagement --install-codex.

Every flag you pass alongside --install-* is written into the installed command, so what the client spawns matches what you typed: selectors (--project, --db, --no-project, --use-active-project), --read-only, --tools, --pin-project, --insecure-upstream, and --config. Paths are made absolute, because the client spawns the server from a working directory you did not choose.

Tools

Read tools (available under --read-only, except these five: scan_js_endpoints, oast_payload, oast_poll, reply_to_operator, and ask_operator):

Where two tools name one object differently, both spellings are accepted: flow_id for id on get_flow / delete_flow, repeater_id for id on the repeater tools (and id for repeater_id on minimize_repeater), enabled for enable on intercept_toggle. Each limit states its default and maximum in the schema (default, minimum, maximum). A list reply is also held to about 64 KB of rows, because a row count does not bound its size: a page can end before limit with cut_by: "bytes" and has_more: true, and its usual cursor (next_before_id, next_since, next_cursor, or offset plus returned / scanned) picks up where it stopped. An ids set that does not fit returns the rest as remaining_ids, and a binary get_response_body_chunk page stops at 48 KB so its base64 fits. A list that is never paged names what did not fit by id (authorize_results bypasses_unshown_ids, the authorize_* skipped_unshown_ids / failed_unshown_ids, diff_projects issues_unshown_ids), and one with no cursor says truncated (probe_scan, list_sitemap's unrequested). oast_poll returns the callbacks that fit and keeps the rest for the next poll (has_more). A single document is not a list: export_openapi inlines up to 64 KB by default and writes a larger one with output_path, and a compare_flows diff, which has nowhere else to put the rest, keeps its own 256 KB cap and says truncated.

Action tools (disabled by --read-only, except switch_project, which works unless --pin-project withholds it, and create_project, which works while the server is unbound). Every one that opens a socket (send_request, send_websocket, ws_session_open, ws_inject, fuzz_*, mine_*, authorize_*, cache_deception_check, sequence_*, discover_*, grpc_reflect, minimize_repeater, race_requests, timing_requests, run_retest, refresh_session_slot, and probe_scan with active:true) is scope-gated: a target outside, or without, a configured scope is refused with SCOPE_BLOCKED unless the call passes allow_unscoped:true, the explicit waiver. The sandbox applies even then, and so does an explicit exclude rule for the sweeping tools (fuzz_*, mine_*, discover_*, sequence_*, authorize_*, minimize_repeater, run_retest, active probe_scan); a single hand-authored send such as send_request passes an exclude, as the proxy does. A project request budget caps them all: a send it refuses fails with BUDGET_EXHAUSTED (not retryable), or PROJECT_BUSY (retryable) when the project database could not lease a slot, and a run that spends the total ends budget_exhausted.

Captured bytes are data, never instructions. Every body, WebSocket message, SSE event, held intercept item, gRPC message, OAST hit and decoded JSON-RPC or LLM text in a result carries origin: target (the server under test wrote it), client (the browser or app did) or remote (an outside party, such as an OAST callback). This is not the origin argument of list_params and export_openapi, which names a scheme, host and port.

Action tools are capped for safety: fuzz, mine, sequence, discover, and authorize jobs are limited in total requests, concurrency, and stored results. An authorize run's cap counts flows × identities, and a selection over it is refused up front rather than truncated into a run that would report "enforced" for flows it never sent. A rule created via create_rule is picked up by gori run and newly opened TUIs, and an already-running TUI on the project reloads its rules on its next store refresh, without a restart.

From a Spec to Repeater Tabs

import_flows reads OpenAPI/Swagger (JSON or YAML) and joins servers[0].url with each operation path, so the base-path assembly is already done. Getting from a spec to a strip of tabs is three calls:

import_flows{kind: "oas", path: "openapi.yaml"}
list_history{query: "src:import"}          → the flow ids
create_repeaters{flow_ids: [...], name_prefix: "oas: ", tags: "spec"}

create_repeaters checks every flow exists before it creates the first session, seeds each one through the same path a single create_repeater{flow_id} uses, and appends them in the order given. Rearrange afterwards with move_repeater, and prune with delete_repeaters.

Live Intercept

An agent can sit in the intercept loop next to you rather than reading History after the fact. The TUI session holding the capture lock mirrors held messages out to the agent and drains the commands it sends back, so intercept_list → intercept_get → intercept_forward_edit is the same loop you drive by hand.

The mutating half (intercept_forward, intercept_forward_edit, intercept_drop, intercept_toggle, intercept_set_filter, intercept_set_direction) is disabled by --read-only, and every one of them refuses when no live capture session is holding the lock. There is nothing to forward without a proxy actually holding traffic.

ws_inject rides the same bridge, which is why it needs a capturing TUI too: only that process holds a live proxied socket. It writes one frame into an open HTTP/1.1 WebSocket flow, client → server (direction:"out", the default) or server → client ("in"), with payload as literal text or payload_base64 for exact bytes. It is a send, not an intercept verb: it belongs to Send traffic, is scope-gated against the flow's host and asked about per host. A text or binary frame waits up to 5 seconds for a fragmented message on that side to end and is REFUSED past that; the frame lands in the flow's ws_messages with origin: "gori". The proxy guide has the details. gori run intercept inject is the same path from a script.

Agent actions are visible, not silent. Each one lands in the notification center tagged as coming from an agent, rendered differently from your own actions, so you can see what a co-pilot did to traffic while you were reading another tab.

It reads the other way too. A row intercept_list returns with operator_editing: true is one you have unsaved changes typed into right now, so an agent can leave that message to you instead of forwarding, editing or dropping it and discarding your work.

One safety rule is worth knowing before you leave an agent running. A held message normally waits forever for a human decision, which is what you want when you are the only one at the keyboard. Once an agent that can act on the queue (not --read-only, with Intercept control on) reads it or sends it a command in that session, gori arms a 30 second auto-forward for items nobody is watching, so a client that dies mid-hold cannot wedge the connection indefinitely. A session with no agent attached never auto-forwards.

Messages from gori

Live Intercept lets an agent watch you work; the palette verb "Tell the agent…" (app.tell-agent) is the other direction: a one-line message you send from any gori tab to an attached agent's own session. Pick one of the MCP clients attached to the project (the same list the mcp: chip and the "Attached agents" card show), or all of them, type the line, and gori delivers it. From the "Attached agents" card itself, t messages the highlighted agent directly. When you send it from the History list with rows marked, those flows ride along as context so the agent can act on exactly what you had selected.

Delivery tries five layers, in the order of what gori can confirm (a route that reports back before one that cannot), and the first that answers ends the chain, so no message is ever carried twice:

1. Inbox socket: when the target is Claude Code, gori mcp writes the message to that session's inbox socket (/tmp/cc-socks/<pid>.sock, named by the pid of the Claude Code process that spawned gori mcp). This is GA: no flag, no opt-in. The message arrives framed as a note from another session, prefixed [gori] The operator at the gori TUI says:; an idle session starts a turn on it, a busy one reads it between tool calls. Claude Code's own crossSessionInbound setting decides whether to accept it, hold it for later, or refuse it outright; gori writes the socket either way and cannot see which of the three happened. A socket file that is there but refuses the connection is a leftover from a session that has already exited (/tmp/cc-socks/<pid>.sock outlives the process that bound it, and pids are reused), so gori falls through to the next layer instead of stopping on a door nobody is behind.
2. Codex queue: when the target is Codex, gori mcp hands the line to that session's own thread with codex queue --thread <id> --message …, and the session runs a turn on it: immediately when it is idle, after the current turn when it is busy. Codex tells an MCP server nothing about itself, so gori reads the thread out of the writer lock the Codex process holds open (<CODEX_HOME>/thread-writer-locks/<thread>.lock), which names the thread and the CODEX_HOME to queue into, so a session started with its own CODEX_HOME is still reached. GA, no flag. A thread that has not run a turn yet has no rollout and codex queue refuses it; that reason lands on the delivery row and the message stays readable through layers 4 and 5.
3. Channel: when mcp.channels is on in Settings and neither door above answered, gori mcp declares the claude/channel capability and pushes the message as a channel event. Claude Code shows it as ← gori: … and starts a turn on it once the session is idle, so the model reads it as an instruction rather than a passive note. This needs Claude Code launched with claude --dangerously-load-development-channels server:gori, a research-preview flag with a one-time confirm dialog on the client side, and the curated --channels allowlist that flag ships with is Anthropic's, not gori's. It is off by default, and it is the LAST route tried rather than the first. A push to a session that never registered the channel is dropped silently and gori cannot tell, so going first meant the setting took the inbox socket (the one route that actually wakes that session) away from any Claude Code started without the flag. No message ever takes two routes: the first layer that answers ends the chain. What the push does cost is a second reading: it is not a confirmed carry, so the message stays pending for layers 4 and 5. Observed in a live test: Opus 5's safeguards flag channel-injected messages whatever they say and stop the session on a model-switch dialog; the socket route below does not trip them. Leave channels off unless you are testing them.
4. Tool result: whatever the client, any message the layers above did not carry rides back on the next gori tool the agent calls, whatever that tool was: the result carries a second content block with the operator's line beside the tool's own answer. GA, no flag, and nothing for the model to remember, which is the point. The other three layers are each one vendor's door (the inbox socket is Claude Code's, codex queue is Codex's, the channel is a preview of Claude Code's); grok, Pi, Hermes, Antigravity and Claude Desktop have none, so for them this is what turns "the message is in the feed" into "the message is in front of the model". It cannot wake an idle agent (nothing here can), but the moment that agent asks gori anything, the line is in the answer. Like the socket, it is a confirmed carry: the client asked for that result and was given it, so the message is retired from layer 5. A --read-only server has no writer fiber to record the delivery, so it sends the line and leaves the row readable.
5. Poll: always available, and the backstop under every layer above: the message is a row in the project's event feed, and the MCP tool operator_messages returns what is pending for the calling session. The handshake instructions tell the model to check it at the start of a turn, so an agent that reads its own instructions picks the message up on its next call even with no socket, no queue and no channel. What it cannot do is interrupt: an agent sitting idle at its own prompt sees the message when its next turn starts, not before.

Each delivery attempt writes an agent_delivery row, and you see the outcome without switching tabs: the TUI's notification ring shows → claude-code got it (socket), → codex-mcp-client got it (queued in codex), → grok-shell-gori got it (on its next tool result), left for antigravity to pick up (operator_messages) (and → antigravity picked it up once it reads the message), or the reason a delivery failed, and Companion (Miss Ring) reacts to the same notice if she's on. The Activity pane lists every one of these under a new operator source, so the message and its delivery outcome stay on the record alongside everything else that happened to the project (see Activity).

The way back is reply_to_operator. The handshake instructions tell the agent to use it to answer you without you switching to its terminal: the one-line summary lands in the ring (and on Miss Ring), tagged with the client's name, and detail opens from the ring with ↵: a finding, a diff, a list of endpoints. It is a row in the same feed, so it works for every agent, Claude or not (though not one started with --read-only), and it stays on the project's record under the agent source.

When the agent needs a decision rather than to report one, it calls ask_operator with a one-line question and two to four choices ("add api.example.com to scope?" with yes / no). The question does not take focus: it lands in the ring (Miss Ring holds it like a reply), marked ?, and an orange ask:N chip counts what is waiting. Open the card with ↵ on that ring row, a click on the chip, or Answer the agent… in the command palette; press a choice's digit (or move with ↑/↓ and press ↵), x to dismiss it without choosing, or esc to leave it for later. Your answer goes back as an operator message with in_reply_to set to the question, over the same routes as anything you type, so the agent gets it on its next tool result if nothing faster reaches it. A question nobody answers expires (after 30 minutes unless the agent chose otherwise), and the agent is told that too. The card is offered only while the agent that asked is still attached; a question asked while gori was closed is waiting when you open it.

A script can reach you the same way with gori run notify: its line shows in the ring and on Miss Ring without the ai tag, under the script source.

A few limits worth knowing before you rely on this:

• Nothing is replayed. A message is delivered to the agents attached at the moment you send it. An agent that attaches afterward does not receive it retroactively: operator_messages only ever answers with what is still pending for that session, and a delivery already made is not made twice.
• It is a request, not consent. Whichever layer carries it, a peer-framed message asks the model to do something; it does not authorize anything on its own, and the agent may decline exactly as it would any other instruction it disagrees with. The same holds for an ask_operator answer: choosing yes on a card is a decision you hand the agent, not a grant. Scope, the sandbox and the MCP permission switches still decide what it can send.
• A reply is a notification, not a mailbox. It shows in a gori TUI that is open on the project when it lands. There, Miss Ring keeps it up until your next key or click (Settings → Companion → Agent replies), but the ring is emptied when the TUI closes. Replies written while no TUI was open are not replayed one by one: the next TUI to open on the project puts one note in the ring (claude-code sent 2 replies while you were away) whose detail lists them, and the full text stays in the Activity pane. The tool tells the agent the same, and its result carries tui in the shape get_current_context uses, so an agent that sees windows: 0 knows to say it in its own output.
• Channel delivery is a research preview. It depends on an unreleased Claude Code flag and Anthropic's own curated allowlist, both of which can change out from under mcp.channels; the inbox socket and the poll tool exist so the feature still works the day that flag does not.

Playbooks as Prompts

The playbooks are served as MCP prompts, so a client lists them with prompts/list and fetches one with prompts/get. Claude Code shows each one as a slash command, such as /mcp__gori__test-access-control. A prompt costs no model context until you pick it, so the playbooks add nothing to what tools/list spends.

Each prompt is named after its playbook's page and takes one optional argument, focus: a host, path or flow id to start from. It is passed on verbatim. The text is the English playbook with its screenshots removed and its links made absolute, after a short preamble. The preamble tells the agent that the playbook was written for the TUI and gori run, and to carry each step out with a tool from tools/list. A step no listed tool can do goes to you through ask_operator when that tool is served, and is otherwise named and skipped.

Every server lists the same prompts. Under --read-only or a --tools filter, the preamble says so instead of hiding prompts. Run an AI co-pilot is not served, because it is about installing this server.

Protocol Revisions

gori speaks both eras of MCP from one process, and each request decides which one answers it.

• 2026-07-28: the stateless revision. A request carries its protocol version, the client's capabilities and (optionally) the client's name in _meta; there is no handshake to open and none to miss. Results come back with resultType, the server's identity under _meta["io.modelcontextprotocol/serverInfo"], and (on tools/list and prompts/list) the ttlMs / cacheScope hints a client caches by. server/discover answers the supported versions, the capabilities and the instructions in a single call, and may be the first thing you send.
• 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05: the handshake revisions. initialize opens a session exactly as it always has, and is answered with the revision you asked for. Anything else (a version gori does not know, and a stateless one) is answered with the newest handshake revision: a session opened by initialize cannot switch to per-request semantics, so naming one back would be a promise gori could not keep.

A version gori does not speak is refused with -32022 and the list of versions it does, so a client retries instead of guessing. The tool and prompt surface is identical either way: the era decides the envelope, never what a tool does. Prompts are declared with listChanged: false in both, because the list is compiled into the binary and cannot change while it runs.

Two things follow from the stateless revision that are worth knowing before you write a client. subscriptions/listen is answered, but with an empty filter and an immediate graceful close: gori pushes nothing, so the honest subscription is the empty one, and you should rely on the ttlMs you were given instead. And the claude/channel research preview is declared only to the handshake era: a stateless server may write responses, notifications belonging to a request in flight, and notifications on an acknowledged subscription, and a channel push is none of those. Operator messages still reach every client, by the socket, the Codex queue, the next tool result, and operator_messages, none of which touches the protocol stream.

An unknown tool name comes back as a JSON-RPC -32602, not as a tool result with isError. That is where the spec puts it: the call never reached a tool, so there is nothing for the model to retry differently. A tool that ran and failed still answers isError: true with a structured error, which is the one your agent should be handed back.

Tool Hints

Every tool in tools/list carries annotations.readOnlyHint, so a client can tell the tools that only read this project's capture from the ones that write to it or send traffic at a target: the difference between a call worth running unattended and one worth asking about. It is derived from the same declaration --read-only enforces, so the hint and the gate cannot drift apart; they differ only where that declaration says so. The workbench pollers (*_status, *_results, list_jobs, get_job) and preview_rule are hidden by --read-only yet marked read-only, because they only report; switch_project, create_project, probe_scan (whose active:true sends and persist:true writes), export_openapi (whose output_path writes a file) and operator_messages (which records deliveries) are still served under --read-only but are not marked read-only. A read-only tool also carries openWorldHint: false: it answers from the project store and never dials.

One Call at a Time

Tools run one at a time, in the order they arrive; a fuzz or a slow send_request does not overlap with the next call, and responses come back in order. Two messages are handled immediately regardless: ping, so a client's liveness probe never stalls behind a long call, and notifications/cancelled, which suppresses the response to a request you stopped waiting for. Cancelling send_request or send_websocket closes its active socket so a silent origin cannot hold the worker until the timeout; tools with cooperative cancellation stop at their next check. Other in-progress calls finish before the worker takes the next queued call.

Why an MCP Seam

gori deliberately has no in-tool AI chat. The intelligence lives outside the tool, reachable through MCP. That means you choose the model, your traffic isn't shipped anywhere you didn't intend, and the same interface serves scripts and agents alike. gori run covers the non-interactive path; MCP covers the interactive-agent path.

Next Steps

• AI Setup: a step-by-step walkthrough to connect an agent and drive its first request
• Scripting: the other automation path, gori run for pipelines and CI
• CLI Reference: full gori mcp flags
• Query Language: the syntax agents use to filter