Repository navigation
Add documentation for the MCP gateway - #580
Merged
Merged
Conversation
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>
|
|
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
approved these changes
Nov 18, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds documentation for the MCP gateway, which is in early access.
Pages
platform/mcp-gateway.mdxtutorials/protect-mcp-servers.mdxtutorials/mcp-gateway-policy.mdxtutorials/mcp-gateway-audit.mdxplatform/mcp-gateway-reference.mdxmanifest.jsonadds 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:
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
Checks
valereports no errors on the five pages. The warnings are the "Step N:" heading style that the other Protect tutorials also use.