feat(mcp): discovery surfaces, registry publish, and the stdio gateway (#9526) (#9735)

* feat(mcp): serve the discovery surfaces and publish server.json

The server card and the agent-tools trio are COMPUTED at request time from the contract
registry. metagraphed committed its card and paid for it: every concurrent tool PR
conflicted on the same generated file. There is nothing here to regenerate and nothing a
tool PR can collide on.

The same routes serve both deployments over their own availability-filtered tool set, so a
self-host card is truthful rather than a copy of the cloud one -- a cloud-only tool is
absent because it is absent from that deployment's list, not because a second
implementation remembered to exclude it. Locality is deliberately NOT filtered: the remote
serves local-git tools too, it just expects the caller to supply the branch metadata.

generated_at derives from the version rather than the clock. A wall-clock value would
change the body on every request, changing the ETag with it and leaving the 304 path as
dead code that never fires.

serverInfo.version stops being the hardcoded "0.1.0" it has reported since the server was
written, and reads the same @loopover/mcp version the compatibility metadata already did --
so serverInfo, the card, and server.json cannot disagree about what shipped.

The manifest check carries the anti-rot guard this issue asked for: it asserts every
watched path EXISTS before validating a field. metagraphed's version-sync workflow watched
a renamed path and kept passing for months while doing nothing, and a workflow that can
quietly watch nothing is worse than no workflow.

* feat(mcp): mount the remote tool set from the stdio server (#9526)

The stdio server now discovers the remote server's tools/list with the login session and
registers anything it does not already serve, so one config gets a contributor every tool
their session entitles them to instead of one stdio config for local-git tools and a
separate remote endpoint for the rest.

The mount is best-effort by design. No session, no network, or a hostile response all leave
a server that starts and lists its local tools plus one advisory resource explaining how to
get the rest; --no-remote opts out to byte-identical pre-gateway behavior. Proxied tools
re-use the contract registry's zod schemas rather than trusting a remote-supplied schema, so
the proxy advertises exactly what the remote enforces, and carry _meta.transport="proxied"
so telemetry can tell a proxied call from a local one.

Name collisions cannot happen by construction — one registry, one entry per name, so a name
is either local-git or remote — and validate:mcp now asserts that invariant. The mount still
skips an already-registered name so a future violation degrades to "local wins" rather than
crashing the server on a duplicate registration.

* feat(mcp): derive every client-config surface and tag proxied calls (#9526)

The three ways to connect -- the stdio gateway, the remote streamable-http endpoint, and the
miner's own stdio server -- were spelled out by hand in four places: clientSnippet() in the
stdio bin, the mcp-clients docs page, and both package READMEs. They had already drifted; the
docs page documented no remote auth at all, and nothing described the gateway because the
prose predates it. The grid now lives in @loopover/contract as data, `init-client --print`
renders it, and a generator writes the docs and README blocks from it under a --check drift
guard, so a snippet copied from the docs and one printed by the CLI are byte-identical.

`init-client` gains `--mode stdio|remote|miner`, defaulting to stdio so a pre-gateway
invocation prints exactly what it always did. A remote entry names the token's environment
variable in whichever dialect the host reads -- Codex's own key, the JSON hosts' header --
and never carries a value; a host whose remote dialect this repo cannot vouch for is refused
rather than given a plausible snippet that fails on paste.

Telemetry gains a `transport` dimension, so gateway adoption is measurable: `surface` says
which server was asked, and only `transport` says whether a stdio call ran against the local
checkout or was forwarded. Proxied tools now run through the same telemetry chokepoint local
ones do, and re-register with the contract's schema OBJECTS rather than their `.shape`, which
the SDK re-wraps in a way that drops the catchall and turns every extra field into a -32602.

The discovery routes are specced through the #9519 seam with real response schemas: the four
documents are now zod schemas with their TypeScript types inferred, so the published operation
describes the object actually served instead of a second declaration of it. They also report
the deployment that ANSWERED -- src/server.ts serves this same Hono app, so a self-host card
was advertising the cloud's tool set, which is a list of calls that 404 there.

Fix-what-you-find, all three the same rot: the vitest alias list for @loopover/contract, the
published-tarball allowlist, and the mount's startup cost. The first two are now derived from
the package's own exports map and its committed sources -- both had just failed by lagging a
new file, with an error naming the symptom and not the cause. The third: the mount moved after
connect() and is no longer awaited, so a network round-trip no longer sits between a client
launching the process and it answering, and registering a tool on a connected server emits
notifications/tools/list_changed -- the refresh path a stateless remote cannot push itself.

* fix(mcp): pin the publisher binary by checksum and gate the publish job (#9526)

Three defects in the registry-publish workflow, two of them raised by the security scan and all
three real.

The install step's comment said "SHA-pinned" while the code floated on a release tag, which a
maintainer can move to a different commit after review -- for a binary that authenticates as this
repository and writes to a public registry. It now verifies a sha256 of the download before
extracting it, so a moved tag fails the job rather than publishing under bytes nobody looked at.

The job holds `id-token: write` and had no deployment environment, so protection rules had nothing
to attach to and anyone able to dispatch a workflow could publish. It now declares one.

And the download would have 404'd regardless: the asset was requested as
`mcp-publisher_${VERSION}_linux_amd64.tar.gz`, but the release publishes it with no version in the
name. A publish workflow that cannot fetch its own tool is a workflow nobody has run, which is
exactly the class the anti-rot guard exists for -- so the guard now covers the workflow itself:
dispatch-only, main-only, environment present, permissions minimal, actions sha-pinned, the
checksum verified before extraction, and the manifest check ordered before login and publish.

Also fixes a genuine flake this PR's CI hit twice, unrelated to the change: selfhost-pg-queue's
recentDeadCount assertion compared the bound cutoff only against a timestamp captured BEFORE the
call, while the implementation reads the clock after it -- so one millisecond ticking between the
two failed the test (1785302335173 <= 1785302335172). Bracketed on both sides now.

* fix(mcp): forward the caller's arguments through a proxied tool (#9526)

Raising the gateway's patch coverage found a real defect in it. registerProxiedTool declared an
inputSchema only for a tool the contract registry knows, and the SDK invokes a handler as
`(args, extra)` ONLY when an inputSchema is declared -- as `(extra)` alone when it is not. So a
proxied tool absent from the registry, which is precisely the case the fallback exists for (a
remote running ahead of this package), forwarded the SDK's own `{ signal, requestId }` to the
remote AS THE ARGUMENTS and silently dropped everything the caller passed.

An unmodelled tool now gets a fully open input schema instead of none, which keeps the remote the
only validator -- where validation belongs for a tool this package does not model -- while making
the SDK route arguments the way it does for every other tool.

The test that caught it was previously asserting only that the call resolved. callTool resolves
for a FAILED call too, so it passed while nothing was being proxied at all: the fixture had no
/mcp route, the proxy 404'd, and the SDK turned the throw into an isError result nobody checked.
The fixture now answers tools/call with a real JSON-RPC envelope and the assertion is on the
payload -- the tool name and the arguments as the remote received them.

Also: the advisory resource is registered on every outcome rather than only on failure, so a
successful mount no longer leaves an earlier failure's advisory standing as the answer to "why
don't I have the remote tools". Plus coverage for the paths that had none -- calling a proxied
tool, reading the advisory, a descriptor carrying annotations, one carrying only a name, an
envelope with no `result`, the real fetch transport against the loopback fixture, and the
no-session path that makes no outbound request at all.

* test(mcp): cover init-client's host and mode guards (#9526)

The five branch partials codecov/patch was holding the PR on, all in init-client's argument
handling: no host at all, an unknown host, the --client spelling as well as --print, a
host/mode pair the grid refuses, and the per-host remote caveat's absent side.

Each asserts the message rather than merely the throw -- "unsupported client" without the list
leaves a reader guessing at a five-value set they cannot see from outside the process.

Author: JSONbored

.github/workflows/publish-mcp-registry.yml

@@ -0,0 +1,85 @@
+name: Publish MCP Registry
+
+# Publishes server.json to the official MCP registry (#9526), so `io.github.JSONbored/loopover` is
+# discoverable by any registry-aware client.
+#
+# workflow_dispatch ONLY, and main-only. Publishing announces a version to a public registry, which is not
+# something a branch build or a merge should do on its own -- the version it advertises comes from
+# @loopover/mcp's package.json, which the release automation bumps, so a publish is a deliberate follow-up to
+# a release rather than a side effect of one.
+#
+# ANTI-ROT: the first step re-runs scripts/check-server-manifest.ts, which asserts every watched path still
+# EXISTS before validating any field. metagraphed's version-sync workflow rotted silently for months because
+# it watched a path that had been renamed -- it kept passing while doing nothing at all. A workflow that can
+# quietly watch nothing is worse than no workflow, so this one fails loudly instead.
+
+on:
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Validate and print what would be published, without publishing"
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+  # GitHub OIDC is how mcp-publisher proves this repo owns the io.github.JSONbored/* namespace. No
+  # long-lived registry credential exists to leak.
+  id-token: write
+
+concurrency:
+  group: publish-mcp-registry
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Publish server.json
+    runs-on: ubuntu-latest
+    # A deployment environment, so the one job in this repo that holds `id-token: write` and writes to a
+    # public registry can carry protection rules (required reviewers, a wait timer) configured outside the
+    # workflow file. Without it, anyone who can dispatch a workflow can publish.
+    environment: mcp-registry
+    # Belt and braces alongside the dispatch-only trigger: a dispatch can name any ref, and a registry
+    # publish must only ever describe what is on main.
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+
+      - name: Setup Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version-file: .nvmrc
+
+      # Runs BEFORE anything else: a manifest whose version disagrees with the shipped package, or a watched
+      # path that has been renamed away, must stop the publish rather than announce something untrue.
+      - name: Validate server.json and its watched paths
+        run: node --experimental-strip-types scripts/check-server-manifest.ts
+
+      - name: Install mcp-publisher
+        env:
+          MCP_PUBLISHER_VERSION: v1.8.0
+          # The tag is mutable; this is not. A release tag can be moved to point at a different commit, and
+          # this binary authenticates as this repository and writes to a public registry -- so the download
+          # is checked against the exact bytes reviewed here, and a mismatch fails the job rather than
+          # publishing under a binary nobody looked at.
+          MCP_PUBLISHER_SHA256: 1370446bbe74d562608e8005a6ccce02d146a661fbd78674e11cc70b9618d6cf
+        run: |
+          set -euo pipefail
+          curl -fsSL "https://github.com/modelcontextprotocol/registry/releases/download/${MCP_PUBLISHER_VERSION}/mcp-publisher_linux_amd64.tar.gz" -o mcp-publisher.tar.gz
+          echo "${MCP_PUBLISHER_SHA256}  mcp-publisher.tar.gz" | sha256sum --check --strict -
+          tar -xzf mcp-publisher.tar.gz mcp-publisher
+          chmod +x mcp-publisher
+
+      - name: Login via GitHub OIDC
+        run: ./mcp-publisher login github-oidc
+
+      - name: Publish
+        if: ${{ !inputs.dry_run }}
+        run: ./mcp-publisher publish
+
+      - name: Dry run — report what would be published
+        if: ${{ inputs.dry_run }}
+        run: |
+          echo "DRY RUN: server.json validated and OIDC login succeeded; publish skipped."
+          cat server.json

apps/loopover-ui/content/docs/mcp-clients.mdx

@@ -4,25 +4,39 @@ description: Configure your coding agent to talk to the LoopOver MCP. Pick stdio
 eyebrow: Get started
 ---
 
+{/* GENERATED:MCP-CLIENT-CONFIG:BEGIN — edit packages/loopover-contract/src/client-config.ts, then `npm run mcp:client-config` */}
+
 ## Generate config
 
-These commands print config only. They do not mutate your local client files.
+Every block on this page is what `init-client` prints. It prints config only — it never edits your client files.
 
 <CodeBlock
   lang="bash"
   code={`loopover-mcp init-client --print codex
 loopover-mcp init-client --print claude
 loopover-mcp init-client --print cursor
 loopover-mcp init-client --print mcp
-loopover-mcp init-client --print vscode`}
+loopover-mcp init-client --print vscode
+loopover-mcp init-client --print codex --mode remote
+loopover-mcp init-client --print claude --mode remote
+loopover-mcp init-client --print cursor --mode remote
+loopover-mcp init-client --print vscode --mode remote
+loopover-mcp init-client --print codex --mode miner
+loopover-mcp init-client --print claude --mode miner
+loopover-mcp init-client --print cursor --mode miner
+loopover-mcp init-client --print mcp --mode miner
+loopover-mcp init-client --print vscode --mode miner`}
 />
 
-`--print mcp` uses the same JSON snippet as Claude Desktop and Cursor for other stdio MCP hosts
-that expect the `mcpServers` shape. Every generated snippet assumes `loopover-mcp` is on your
-`PATH` (install it globally first, per [Quickstart](/docs/quickstart)) — pass
-`--command /absolute/path/to/loopover-mcp` if your client doesn't inherit your shell PATH.
+## Local stdio (gateway)
+
+The recommended default. Runs `loopover-mcp` on your machine, keeps auth and git analysis local, and — once you have run `loopover-mcp login` — mounts the remote tool set too, so one entry serves every tool your session entitles you to.
 
-## Codex (OpenAI)
+- Run `loopover-mcp login` before starting the client; without a session you get the local-git tools only, plus an advisory resource explaining how to get the rest.
+- Pass `--no-remote` to keep the server purely local and skip the remote mount entirely.
+- Assumes `loopover-mcp` is on your PATH; pass `--command /absolute/path/to/loopover-mcp` if your client does not inherit your shell PATH.
+
+### Codex (OpenAI) (stdio)
 
 <CodeBlock
   filename="~/.codex/config.toml"
@@ -32,7 +46,7 @@ command = "loopover-mcp"
 args = ["--stdio"]`}
 />
 
-## Claude Desktop
+### Claude Desktop / Claude Code (stdio)
 
 <CodeBlock
   filename="claude_desktop_config.json"
@@ -47,7 +61,7 @@ args = ["--stdio"]`}
 }`}
 />
 
-## Cursor
+### Cursor (stdio)
 
 <CodeBlock
   filename=".cursor/mcp.json"
@@ -62,10 +76,22 @@ args = ["--stdio"]`}
 }`}
 />
 
-## VS Code
+### Other `mcpServers` hosts (stdio)
+
+<CodeBlock
+  filename="mcp.json"
+  lang="json"
+  code={`{
+  "mcpServers": {
+    "loopover": {
+      "command": "loopover-mcp",
+      "args": ["--stdio"]
+    }
+  }
+}`}
+/>
 
-VS Code's native MCP support uses a `servers` map with an explicit transport type instead of the
-`mcpServers` shape the other JSON hosts use:
+### VS Code (stdio)
 
 <CodeBlock
   filename=".vscode/mcp.json"
@@ -81,14 +107,163 @@ VS Code's native MCP support uses a `servers` map with an explicit transport typ
 }`}
 />
 
-## Remote MCP
+## Remote streamable-http
+
+For agents that run in the cloud, or anywhere you do not want a local Node process. Connects straight to the hosted server; the local-git tools are not available over this transport because there is no local checkout to read.
+
+- Authenticates with a bearer token read from `LOOPOVER_API_TOKEN` — the same variable the CLI honors. Set it in the environment your client starts in; never paste the token into the config file.
+- Tools whose work is a local git operation are absent here by design. Use the stdio mode if you need them.
+
+### Codex (OpenAI) (remote)
+
+<CodeBlock
+  filename="~/.codex/config.toml"
+  lang="toml"
+  code={`[mcp_servers.loopover]
+url = "https://api.loopover.ai/mcp"
+bearer_token_env_var = "LOOPOVER_API_TOKEN"`}
+/>
+
+Codex releases before its RMCP client became the default also need `experimental_use_rmcp_client = true` at the top level of config.toml.
+
+### Claude Desktop / Claude Code (remote)
+
+<CodeBlock
+  filename=".mcp.json"
+  lang="json"
+  code={`{
+  "mcpServers": {
+    "loopover": {
+      "type": "http",
+      "url": "https://api.loopover.ai/mcp",
+      "headers": {
+        "Authorization": "Bearer \${LOOPOVER_API_TOKEN}"
+      }
+    }
+  }
+}`}
+/>
+
+### Cursor (remote)
+
+<CodeBlock
+  filename=".cursor/mcp.json"
+  lang="json"
+  code={`{
+  "mcpServers": {
+    "loopover": {
+      "type": "http",
+      "url": "https://api.loopover.ai/mcp",
+      "headers": {
+        "Authorization": "Bearer \${LOOPOVER_API_TOKEN}"
+      }
+    }
+  }
+}`}
+/>
+
+### VS Code (remote)
+
+<CodeBlock
+  filename=".vscode/mcp.json"
+  lang="json"
+  code={`{
+  "servers": {
+    "loopover": {
+      "type": "http",
+      "url": "https://api.loopover.ai/mcp",
+      "headers": {
+        "Authorization": "Bearer \${LOOPOVER_API_TOKEN}"
+      }
+    }
+  }
+}`}
+/>
+
+## Miner stdio
+
+AMS's own local state-visibility tools, as a separate stdio server. It stays separate on purpose: it reads this machine's SQLite state and shares no code or network path with the hosted server.
+
+- Takes no flags and needs no login — everything it reads is already on this machine.
+- A dual-role operator runs this alongside the stdio gateway; the two entries coexist in one client config.
+
+### Codex (OpenAI) (miner)
+
+<CodeBlock
+  filename="~/.codex/config.toml"
+  lang="toml"
+  code={`[mcp_servers.loopover-miner]
+command = "loopover-miner-mcp"
+args = []`}
+/>
+
+### Claude Desktop / Claude Code (miner)
+
+<CodeBlock
+  filename="claude_desktop_config.json"
+  lang="json"
+  code={`{
+  "mcpServers": {
+    "loopover-miner": {
+      "command": "loopover-miner-mcp",
+      "args": []
+    }
+  }
+}`}
+/>
+
+### Cursor (miner)
+
+<CodeBlock
+  filename=".cursor/mcp.json"
+  lang="json"
+  code={`{
+  "mcpServers": {
+    "loopover-miner": {
+      "command": "loopover-miner-mcp",
+      "args": []
+    }
+  }
+}`}
+/>
+
+### Other `mcpServers` hosts (miner)
+
+<CodeBlock
+  filename="mcp.json"
+  lang="json"
+  code={`{
+  "mcpServers": {
+    "loopover-miner": {
+      "command": "loopover-miner-mcp",
+      "args": []
+    }
+  }
+}`}
+/>
+
+### VS Code (miner)
+
+<CodeBlock
+  filename=".vscode/mcp.json"
+  lang="json"
+  code={`{
+  "servers": {
+    "loopover-miner": {
+      "type": "stdio",
+      "command": "loopover-miner-mcp",
+      "args": []
+    }
+  }
+}`}
+/>
 
-The Worker also exposes a remote MCP endpoint. Use this when your agent runs in the cloud or you
-don't want a local Node process.
+Every block above comes from the same grid the CLI prints from, so a snippet copied from here and one printed by `init-client` can never disagree.
 
-<CodeBlock lang="http" code={`https://api.loopover.ai/mcp`} />
+{/* GENERATED:MCP-CLIENT-CONFIG:END */}
 
 <Callout variant="safety">
   Local `--stdio` is the default recommendation. It keeps auth + analysis on your machine and is the
-  easiest path to log into with GitHub Device Flow.
+  easiest path to log into with GitHub Device Flow — and, since it mounts the remote tool set too, it
+  is the only mode that gives you every tool from one entry.
 </Callout>