Connect an External Agent to Your Stack

TL;DR

Create a client token under Settings → Stack MCP on a self-hosted Stack, then point your agent's Streamable HTTP MCP client at /mcp with that token. The agent can read the Stack's documentation and snapshot and raise a Proposal, but it can't apply changes or read secrets. Hosted Stacks don't serve Stack MCP.

Stack MCP gives an agent on your laptop read-only access to the version-matched documentation and the same point-in-time Stack snapshot a Guide Session uses. It can raise a Proposal for your review, but it can't apply changes or read secrets.

Stack MCP runs only on a self-hosted Stack

A hosted Stack's Dashboard is on the public internet, so hosted Stacks don't offer Stack MCP at all: the Settings panel is absent and /mcp always returns 404 Not Found. The Dashboard's own Guide still works on a hosted Stack, because it doesn't use /mcp.

Create a client token

Open Dashboard → Settings → Stack MCP, enter a name that identifies the client, and select Create token. Copy the token when it appears. Zozo stores only its hash, so the token can't be shown again.

Creating the first token enables the endpoint. You can turn the endpoint off independently without revoking tokens. When it's off, or after every token has been revoked, /mcp returns 404 Not Found. The Dashboard bearer token and browser session cookie don't work on this endpoint.

Configure your client

Use your Dashboard's origin with /mcp and pass the client token as a Bearer token. A typical Streamable HTTP MCP configuration has this shape:

{
  "mcpServers": {
    "zozo-stack": {
      "type": "streamable-http",
      "url": "http://localhost:8787/mcp",
      "headers": {
        "Authorization": "Bearer zozo_mcp_REPLACE_ME"
      }
    }
  }
}

The exact outer key can vary by agent. Use its Streamable HTTP transport, not an stdio command.

The server offers four tools:

• docs_search searches the documentation shipped with the running Stack.
• docs_read reads a documentation file returned by search.
• settings_read reads one of the synthetic Workspace JSON files under settings/ or status/. The tool schema lists the available paths.
• propose_change raises a Proposal with a target, new value, snapshot revision, and one-line rationale. The target allow-list and validation are identical to Guide-raised Proposals.

Snapshot reads have the same JSON shape and trailing newline as the Guide's Workspace files. They're refreshed for each tool call.

The hosting object in settings/stack.json reports the Stack as self-hosted, and includes the current Onramp phase. It includes the created Stack Slug only after the Onramp is done. This is a point-in-time snapshot, so read the file again when you need current state. Environment keys and claim URLs are never included.

Read settings/stack.json before calling propose_change, then pass its revision as snapshotRevision. The Proposal is attributed to the client token's name and appears in Needs Attention and the Stack's pending Proposal list, even when no Guide Session is open. A signed-in person can apply or dismiss it in the Dashboard. Apply refuses if the setting has changed since that snapshot. Stack MCP deliberately has no apply tool.

Revoke access

The client list shows when each token was created and when it was last used. Select Revoke, then confirm. Revocation takes effect on the next request. Create a separate token for every client so you can revoke one without interrupting another.