docs: MCP server configuration guide#1138
docs: MCP server configuration guide#1138arc-claw-bot wants to merge 1 commit intonearai:stagingfrom
Conversation
Covers the three transport types (HTTP, stdio, Unix), OAuth 2.1 authentication, environment variables for stdio servers, custom headers, the mcp-servers.json config format, example servers, and troubleshooting. Written against the current implementation in src/tools/mcp/ and src/cli/mcp.rs.
github-actions
bot
added
scope: docs
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a new, comprehensive documentation guide for configuring Model Context Protocol (MCP) servers within IronClaw. The guide aims to empower users to seamlessly integrate external tools and data sources by detailing various transport mechanisms, CLI commands for server management, configuration file specifics, and authentication methods like OAuth 2.1/PKCE and custom headers. It also provides practical examples and troubleshooting tips to ensure a smooth user experience. Highlights
Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new documentation file, docs/MCP_SERVERS.md, which serves as a guide for configuring MCP servers. The documentation is comprehensive, covering various transports, CLI commands, and troubleshooting steps. My review identified a critical error in the example mcp-servers.json configuration file structure, as well as an opportunity to improve the troubleshooting section by documenting a relevant CLI command instead of suggesting manual file edits. I have provided specific suggestions to address these points.
| { | ||
| "servers": { | ||
| "filesystem": { | ||
| "name": "filesystem", | ||
| "url": "", | ||
| "transport": { | ||
| "transport": "stdio", | ||
| "command": "npx", | ||
| "args": ["@anthropic/mcp-filesystem", "/home/user/documents"], | ||
| "env": {} | ||
| }, | ||
| "enabled": true, | ||
| "description": "Sandboxed file access" | ||
| }, | ||
| "notion": { | ||
| "name": "notion", | ||
| "url": "https://mcp.notion.com", | ||
| "oauth": { | ||
| "client_id": "your-client-id", | ||
| "scopes": ["read", "write"] | ||
| }, | ||
| "enabled": true | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
The JSON structure for mcp-servers.json is incorrect. The servers field should be a JSON array of server configuration objects, not an object mapping server names to configurations. This can be seen from the McpServersFile struct definition in src/tools/mcp/config.rs, where servers is a Vec<McpServerConfig>. Manually editing the file with the documented structure will lead to parsing errors.
{
"servers": [
{
"name": "filesystem",
"url": "",
"transport": {
"transport": "stdio",
"command": "npx",
"args": ["@anthropic/mcp-filesystem", "/home/user/documents"],
"env": {}
},
"enabled": true,
"description": "Sandboxed file access"
},
{
"name": "notion",
"url": "https://mcp.notion.com",
"oauth": {
"client_id": "your-client-id",
"scopes": ["read", "write"]
},
"enabled": true
}
]
}| ironclaw mcp auth <server-name> | ||
|
|
||
| # Disable without removing | ||
| # Edit ~/.ironclaw/mcp-servers.json, set "enabled": false |
There was a problem hiding this comment.
The documentation suggests manually editing the configuration file to disable a server. While this works, there is a dedicated CLI command ironclaw mcp toggle for this purpose which is safer and more user-friendly. You should document this command instead. You can use --disable or --enable flags, or just toggle to flip the state.
| # Edit ~/.ironclaw/mcp-servers.json, set "enabled": false | |
| ironclaw mcp toggle --disable <server-name> |
henrypark133
left a comment
henrypark133
left a comment
There was a problem hiding this comment.
Review: useful guide, but the config-file example is not the format IronClaw actually reads
The guide is directionally good and covers the right concepts, but there is one blocking correctness issue before I’d merge it.
Critical: mcp-servers.json is documented with the wrong top-level structure
The example shows:
serversas an object keyed by server name
But McpServersFile currently stores:
serversas a list ofMcpServerConfigschema_versionas a top-level field
Right now a reader who copies the example will produce a config file that does not match the real serde shape.
Minor: the troubleshooting section should use the existing toggle command
For “disable without removing”, the docs currently tell users to edit the JSON file manually. The CLI already has ironclaw mcp toggle <name> --disable, which is a better first recommendation.
2 participants
Adds
docs/MCP_SERVERS.md— a practical guide for configuring MCP servers with IronClaw.Written against the current implementation (
src/tools/mcp/,src/cli/mcp.rs) as of March 2026, covering:mcp add,test,list,remove,auth~/.ironclaw/mcp-servers.jsonstructure with transport-specific fieldsThis replaces #777 which was rightfully closed as stale. Rewrote from scratch based on the actual Rust source (McpServerConfig, McpTransportConfig, OAuthConfig structs, CLI arg definitions).
Documentation only — no code changes.