Repository navigation
docs(docs): add bring your own MCP servers guide for Coder Agents - #31495
Merged
Merged
Conversation
nickvigilante
left a comment
Contributor
There was a problem hiding this comment.
Documentation review
I checked the new page, the link from Extending agents, and the sidebar entry against the code on this PR's base.
Details and suggestions are in the inline comments.
Blockers
-
docs/manifest.json:genandofflinedocsfail because the sidebar entry was added by hand instead of indocs/manifest/ai-coder/agents.yml. - Lines 7, 15, and 185-187: existing chats do get
.mcp.jsonchanges, so readers don't need a new chat. - Lines 96-98: the startup script can stop the template's
git-clonemodule from cloning into the working directory. - Lines 120-123: the dotfiles and personalize scripts must be executable.
- Lines 75 and 90: a secret's name is confused with its environment variable target.
Outside this PR
These existing pages conflict with the new page or with the code:
extending-agents.md:449-452has the same outdated claim about existing chats, and #31226 rewrites it.user-guides/user-secrets.md:109says env secrets are injected into the agent's process environment.
The agent applies them to each child process (updateCommandEnv), as line 77 of the new page correctly says.platform-controls/agent-isolation.md:104setsCODER_AGENT_EXP_MCP_CONFIG_FILESincoder_agent.env, which reaches only child processes.
The agent reads that variable from its own environment at startup (cli/agent.go:299).
Other notes
- The examples use Bash,
chmod, andumask, and Windows agents also read.mcp.json, so a line saying the examples assume a Linux or macOS workspace would scope them. prepare-linkspector-browserfailed at checkout, so CI didn't check links.
I checked the relative links and anchors by hand, and they resolve.- #29324 would make Coder accept
streamable-http, which changes line 161.
The rest of the page matches the code: the dir requirement, the server-name rules, the type values, where ${VAR} expands, secret inheritance by stdio servers, connecting after startup scripts, the file watcher, the 30-second and 60-second timeouts, the lack of OAuth, and the CODER_AGENT_EXP_MCP_CONFIG_FILES behavior.
🤖 Review generated with Coder Agents on behalf of @nickvigilante.
Move the sidebar entry into docs/manifest, fix chat refresh, secret naming, script ordering, and executable-bit guidance. Generated by Coder Agents on behalf of @nickvigilante.
Contributor
|
Applied all review suggestions in 3033d9e, moved the sidebar entry into Generated by Coder Agents on behalf of @nickvigilante. |
nickvigilante
enabled auto-merge (squash)
November 3, 2026 13:24
nickvigilante
approved these changes
Nov 3, 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 subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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 a user-facing Bring your own MCP servers page for Coder Agents, aimed at developers coming from Claude Code who want
claude mcp add-style personal servers without an org admin registering each one.The page compares the three options (workspace
.mcp.json, organization MCP servers, inline MCP servers), then walks through writing.mcp.jsonfrom dotfiles or~/personalize, keeping tokens in user secrets, and reusing a Claude Code setup. It also links the page from Extending agents and adds it to the manifest.Behavior verified against
main:.mcp.jsonresolves relative to the agent'sdir. With nodir, no file is read (agent/agentcontextconfig,agent.goworkingDirFn).updateCommandEnv.${VAR}expansion only applies toenvvalues and uses the agent process env, which doesn't include user secrets (agent/x/agentmcp/config.go).typevalues arestdio,http,sse.streamable-httpis not accepted yet (feat: accept streamable-http MCP type, add plugin data dir helper #29324 would change that)..mcp.json. MCP-only edits don't mark existing chats out of date.The
claude mcp add --scope projectexample follows Claude Code's docs and hasn't been tested end to end in a Coder workspace.markdownlint-cli2,markdown-table-formatter, and Vale pass on the new page.Requested in Slack by Michael Suchacz, prompted by a customer ask for BYO MCP in Coder Agents.