docs(mcp): document SSE transport and correct policy semantics#1171
Merged
Conversation
The MCP configuration guide only covered http and stdio, while the CLI already implements and tests the sse transport. It also misstated the config hierarchy and enterprise policy behavior. - Document all three transports (stdio, http, sse) with an SSE add command and mcp.json example - Expand the schema: type union includes sse, stdio type is optional, and remote oauth overrides (scopes, clientId, clientSecret, callbackPort) are enumerated - Add the folder-level .factory/mcp.json source and reference organization-managed settings in the hierarchy - Correct mcpPolicy semantics: enforcement only when enabled is true, allowlist matches URL hostnames or stdio command/args, and disallowed servers are retained but filtered from connecting Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Contributor
|
Droid finished @factory-ain3sh's task —— View job Strong docs update overall; remaining gaps are doc-set inconsistencies (CLI reference + JP page) and a couple of security footguns where examples/schema could encourage plaintext HTTP or committing secrets. |
factory-ain3sh
added
the
documentation
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
…-79) Review feedback (David Gomez-Urquiza): the prior wording implied http and sse are unrelated peer transports. Per the MCP spec, Streamable HTTP (--type http) already streams over SSE internally and replaced the 2024-11-05 HTTP+SSE transport; --type sse is that legacy standalone endpoint, kept for older servers. Reword the transports intro and SSE section to reflect this and steer users to http by default. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
![factory-droid[bot]](https://avatars.githubusercontent.com/in/358017?s=60&v=4){kind=small}
…tps (DR-79) droid-review (PR #1171) flagged doc-set inconsistencies and security footguns: - cli-reference: list sse alongside http/stdio for --type and in the quick-reference command block - become-a-power-user: fix the Linear example (/sse with --type http was contradictory) to /mcp with --type http - mcp.mdx: add a Warning not to commit secrets (headers tokens, oauth.clientSecret) in repo-committed project config - mcp.mdx: correct the Stytch example to https:// (canonical per Stytch docs; http:// was wrong) JP pages are intentionally not hand-edited — the Sync Japanese Docs workflow regenerates docs/jp/** from these EN changes on merge. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
factory-davidgu
approved these changes
Jun 1, 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
2 participants
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.
Description
The public MCP configuration guide had drifted from the shipped Droid CLI: it documented only
httpandstdiotransports, while the CLI already implements and testssse, and it misstated the configuration hierarchy and enterprise-policy behavior. This PR bringsdocs/cli/configuration/mcp.mdxback in line with the current implementation — adding SSE coverage, expanding the schema, documenting the folder-level and org-managed configuration sources, and correcting themcpPolicysemantics. Per the MCP spec, the page now frameshttpas Streamable HTTP (the current standard, which streams over SSE internally) andsseas the legacy standalone HTTP+SSE transport kept for older servers, steering users tohttpby default. Content verified as accurate (registry and interactive-manager guidance) is left intact.Related Issue
Closes DR-79
Constraint from: review feedback (David Gomez-Urquiza) — the transport wording must not imply
httpandsseare unrelated peers, since Streamable HTTP already uses SSE for streaming.Reviewer Guide
Read order:
docs/cli/configuration/mcp.mdx— single file. Review top-to-bottom; the four substantive areas are the CLI transports intro + new "Adding SSE Servers" section, the Configuration hierarchy table, the Configuration Schema, and the Enterprise MCP policy table.Review depth: Standard — verify the wording matches implementation intent, especially the inverted
mcpPolicy.enabledsemantics and the allowlist matching rules.Open for pushback: the folder-level precedence wording in "How Layering Works" (user → folder → project) is stated conservatively; tighten it if the implementation defines a more specific ancestor ordering.
Risk & Impact
Documentation-only change; no code paths affected. The primary risk is conveying incorrect behavior, so the corrections are the point: the previous
mcpPolicy.enableddescription was inverted ("falseblocks all servers") and the allowlist was described as matching server names rather than URL hostnames / stdio command+args. Readers acting on the old text would have misconfigured enterprise policy.Verification
Behavior verified.
mintlify broken-linksrun against the docs project —success no broken links found, including the new in-page anchor#enterprise-mcp-policyadded to the hierarchy section. Rendered structure reviewed: new SSE section mirrors the existing HTTP section, schemaoauthoverrides are enumerated, and themcp.jsonexamples are valid JSON. Transport descriptions were cross-checked against the MCP transport spec (2024-11-05 HTTP+SSE vs 2025-06-18 Streamable HTTP) after reviewer feedback.Regression coverage. N/A — prose docs; no test layer. The link checker is the only automated gate and it passes.
Not tested. Field-level accuracy (e.g., exact
oauthoverride key names, allowlist matching internals) is transcribed from the DR-79 implementation evidence rather than re-derived here, since this repo contains only docs, not the CLI source.Standard validators. No format/lint/typecheck/test tooling in this docs repo;
mintlify broken-linksclean.