Skip to content

Add documentation for the MCP gateway - #580

Merged
tashian merged 7 commits into
mainfrom
docs/mcp-gateway
Nov 19, 2026
Merged

tashian merged 7 commits into
mainfrom
docs/mcp-gateway

Conversation

@joshdrake

Copy link
Copy Markdown
Contributor

Adds documentation for the MCP gateway, which is in early access.

Pages

Page What it covers
platform/mcp-gateway.mdx Concepts: what the gateway does, how a request flows, hardware-attested and hardware-bound keys, where the OAuth token lives, the three policy modes, what is recorded, and what the gateway does not do
tutorials/protect-mcp-servers.mdx Setup: trust roots, registering an OAuth app, adding an MCP server, approving access from a device, connecting Claude Code, and common problems
tutorials/mcp-gateway-policy.mdx Policy: start from the baseline, turn on Monitor, write and activate a Cedar statement, see what it would refuse, enforce it, roll back
tutorials/mcp-gateway-audit.mdx Audit: sessions, timelines, decisions, events, argument capture, ending a session
platform/mcp-gateway-reference.mdx Reference: the Cedar schema and actions, example policies, modes, limits, session and decision values, audit events, timings, roles, agent commands and messages

manifest.json adds a "Smallstep MCP Gateway" group after "Protect". That change is its own commit, so it can be dropped if the pages should stay out of the sidebar for now.

How the pages were checked

Every procedure was run with Smallstep Agent 0.70.0 and Claude Code 2.1.327 on Linux, with Linear as the MCP server, on two separate teams. Console text, command output, and error messages in the pages are copied from those runs.

Not run by hand, and written from the product's source instead:

  • What a Device Admin can see.
  • The failure when the gateway's trust roots do not match the device's certificate.
  • The live update of an open session's timeline.

Not tested at all: macOS, Windows, and MCP clients other than Claude Code. The setup guide says which versions it was tested with.

For reviewers

  • Terms. The pages say "MCP server" for the thing the console lists under MCP Proxies, and say so once in the concept page. They use "token broker" for the service that holds OAuth grants.
  • Stage. Each page carries an "early access" note that points to support.
  • Example policy. The worked example refuses Linear tools by name prefix. The pages say plainly that this is not a read-only policy, and why.
  • OAuth app. The setup guide says an OAuth app is required for every MCP server, including the catalog entries.

Checks

  • vale reports no errors on the five pages. The warnings are the "Step N:" heading style that the other Protect tutorials also use.
  • The pages have not been rendered locally; this repository has no build step.

joshdrake and others added 6 commits November 17, 2026 17:37
Add two pages for the MCP gateway, which is in early access:

- platform/mcp-gateway.mdx explains what the gateway does, how a
  request flows, what the device certificate proves, where the OAuth
  token lives, the three policy modes, what is recorded, and what the
  gateway does not do.
- platform/mcp-gateway-reference.mdx lists the Cedar policy schema and
  actions, example policies, modes, limits, session and decision
  values, audit events, timings, roles, agent commands and messages.

The pages are not in manifest.json yet, so nothing links to them.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Add tutorials/protect-mcp-servers.mdx with the steps checked on a
test team: set the gateway's trust roots, register an OAuth app, add
the MCP server, and approve access from a device. The steps that
follow approval (a successful tool list and an MCP client) are not
written yet, because they have not been run.

In the reference page:

- Show audit events by the labels the console displays.
- Replace the IDs in the refused-call example with made-up values.
- Separate the three baseline statements from the example that blocks
  tools by name, and say what a name match does not cover.
- Reduce the roles table to what each role can do in the console.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Complete tutorials/protect-mcp-servers.mdx with the steps after a
person approves access: the tool list, connecting Claude Code, finding
the session, and common problems.

Add tutorials/mcp-gateway-policy.mdx, which takes one policy from the
baseline through Monitor to Enforce and back, and
tutorials/mcp-gateway-audit.mdx, which covers sessions, timelines,
decisions, events, argument capture, and ending a session.

Every step was run on a test team with Smallstep Agent 0.70.0 and
Claude Code on Linux. The reference page now records what that run
showed: how a refused call reads in a timeline, what the agent prints
after a session is revoked, and when a token exchange entry is absent.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Add a "Smallstep MCP Gateway" group after "Protect" with the concept
page, the three guides, and the reference page.

This commit is separate so it can be dropped if the pages should stay
out of the sidebar.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
- Audit guide: the "would have refused" line appears when decisions in
  the range have that outcome, not whenever the mode is Monitor.
- Policy guide: returning to Monitor takes up to 30 seconds, like
  every other mode change.
- Policy guide: say that "Start from the baseline" appears only while
  the team has no policies, and what to check otherwise.
- Setup guide: remove an unchecked statement about which Linear role
  can register an OAuth app.

Not everything in these pages was run by hand in the console. The
OAuth app was registered by a person; the example policy was saved and
activated through the API; the simulator was not run against a forbid
statement; "claude mcp add" was run with project scope only; the
Device Admin role, the trust-roots failure row, and the live timeline
refresh come from reading the code.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The pages were checked again on that date with a second team: the tool
list, Monitor and Enforce decisions, ending a session, a Claude Code
run, and a timeline with argument capture off all matched what the
pages describe.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@CLAassistant

CLAassistant commented Nov 18, 2026 •

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ tashian
❌ joshdrake
You have signed the CLA already but the status is still pending? Let us recheck it.

Add steps to make an MCP bundle (.mcpb) file for Claude Desktop.
An admin sends the bundle to the team, and each person installs
the MCP server with drag-and-drop. Each person approves access to
the MCP server one time before the install.

Put the Claude Code steps in their own section. Make the MCP
gateway overview page shorter, and make its headings shorter.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tashian
tashian marked this pull request as ready for review November 19, 2026 19:58
@tashian
tashian requested a review from a team as a code owner November 19, 2026 19:58
@tashian
tashian merged commit a28928b into main Nov 19, 2026
3 of 4 checks passed
@tashian
tashian deleted the docs/mcp-gateway branch November 19, 2026 19:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants