docs: add MCP server examples guide#777
Conversation
Add docs/MCP_SERVERS.md with: - Quick start commands for adding MCP servers - Transport type overview (HTTP, stdio, Unix) - Example configurations for popular servers (Fulcra Context, Filesystem, PostgreSQL) - Configuration file format reference - Links to MCP vs WASM decision guide and server directories
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 comprehensive documentation to guide users on configuring and utilizing Model Context Protocol (MCP) servers within the IronClaw ecosystem. It addresses a critical gap by providing practical examples and setup instructions, enabling users to effectively extend their agents with third-party tools. The new guide covers various transport types, offers concrete server examples, and clarifies configuration details, significantly enhancing the user experience for MCP integration. 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
|
github-actions
bot
added
size: XS
![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 adds a new documentation file, docs/MCP_SERVERS.md, which is a guide for configuring MCP servers. The guide is well-structured and provides useful examples. I've identified a couple of areas for improvement: the configuration file example could be more comprehensive by including a stdio transport example, and a link to a "decision guide" appears to be pointing to the wrong file. Addressing these points will make the documentation even more helpful for users.
Note: Security Review has been skipped due to the limited scope of the PR.
| { | ||
| "servers": [ | ||
| { | ||
| "name": "fulcra", | ||
| "url": "https://mcp.fulcradynamics.com/mcp", | ||
| "enabled": true, | ||
| "description": "Personal context data — biometrics, sleep, activity, calendar, location" | ||
| } | ||
| ] | ||
| } |
There was a problem hiding this comment.
The configuration file example only shows a server with an implicit HTTP transport. To improve clarity for users who may need to manually edit mcp-servers.json, it would be beneficial to include an example of a server using stdio transport as well. This would demonstrate the structure of the transport object.
{
"servers": [
{
"name": "fulcra",
"url": "https://mcp.fulcradynamics.com/mcp",
"enabled": true,
"description": "Personal context data — biometrics, sleep, activity, calendar, location"
},
{
"name": "filesystem",
"url": "",
"enabled": true,
"transport": {
"transport": "stdio",
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/path/to/allowed/dir"
]
}
}
]
}|
|
||
| ## When to Use MCP vs WASM | ||
|
|
||
| See the [decision guide in TOOLS.md](../tools-src/TOOLS.md) for guidance on choosing between MCP servers and native WASM tools. In general: |
There was a problem hiding this comment.
The link to the "decision guide in TOOLS.md" appears to be incorrect. The linked file, tools-src/TOOLS.md, is a feature checklist rather than a guide explaining when to choose MCP over WASM. This could confuse users. Please update the link to point to the correct document, or add the decision guide content to tools-src/TOOLS.md.
zmanian
left a comment
zmanian
left a comment
There was a problem hiding this comment.
Review: docs/MCP_SERVERS.md
The guide is well-written and fills a real gap. However, it contains several factual errors that would mislead users. The main issue is that IronClaw only supports HTTP transport for MCP servers today -- stdio and Unix socket transports are not implemented. The CLAUDE.md explicitly lists "MCP stdio transport - Only HTTP transport implemented" as a current limitation.
Factual errors
-
Stdio and Unix socket transports do not exist. The
ironclaw mcp addcommand accepts only<name> <url>-- there are no--transport,--command, or--argflags (seesrc/cli/mcp.rslines 22-50). The transport table, the stdio examples (Fulcra local, Filesystem, PostgreSQL), and any mention of--transport stdioor--command/--argare incorrect and will fail at the CLI. -
The configuration file format is incomplete. The actual
McpServerConfigstruct (src/tools/mcp/config.rs) includesoauth,enabled, anddescriptionfields, and the file has aschema_versionfield. The example JSON in the doc omitsschema_versionand doesn't mention that the real format looks different from what's shown. More importantly, it shows onlyname,url,enabled,description-- but the actual serialized format also includesoauthwhen present. -
Broken link. The "decision guide" link points to
../tools-src/TOOLS.mdbut fromdocs/MCP_SERVERS.mdthe correct relative path would be../src/tools/README.md(that's where the "WASM Tools vs MCP Servers: When to Use Which" section lives).
Suggestions
- Remove all stdio/Unix socket content, or clearly label it as "planned/future" with a note that only HTTP transport is currently supported.
- Remove or rewrite the Filesystem and PostgreSQL examples since they require stdio transport. You could replace them with HTTP-based MCP server examples.
- Rewrite the Fulcra example to show only the remote (HTTP) variant, which is the one that actually works today.
- Fix the TOOLS.md link to point to
../src/tools/README.md. - Consider adding the
schema_versionfield to the config file example for accuracy.
Minor nits
- The Quick Start section shows
ironclaw mcp list --verbosebut the actual flag is--verbose(short:-v). This is correct. - The
ironclaw mcp auth <name>command is accurately described.
|
Closing — bot-generated docs PR, stale relative to current MCP implementation. |
2 participants
Summary
Adds
docs/MCP_SERVERS.md— a practical guide for configuring MCP servers with IronClaw.What's included
ironclaw mcp add/test/listmcp-servers.json)Motivation
IronClaw's MCP support is well-implemented but there's no user-facing guide showing how to actually configure servers. This fills that gap with practical examples that users can adapt.
Checklist
FEATURE_PARITY.md— no changes needed (MCP support already tracked as ✅)