lywsvip/ironclaw
1
0
Fork 0
mirror of https://github.com/nearai/ironclaw.git synced 2026-09-02 23:56:24 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: MCP server configuration guide (#1138)

Browse Source 
* docs: add MCP server configuration guide

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.

* fix: docs

* chore: better explain toggle

---------

Co-authored-by: Guille <gagdiez.c@gmail.com>
Co-authored-by: Guillermo Alejandro Gallardo Diez <gagdiez@iR2.local>
This commit is contained in:
arc-claw-bot
2026-04-17 09:13:11 -04:00
committed by GitHub
parent 89b350ec56
commit 2874d2e98f
2 changed files with 175 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

173
docs/capabilities/mcp.md Normal file
View File

@@ -0,0 +1,173 @@
---
title: Model Context Protocol (MCP)
description: Connect your agent to Model Context Protocol (MCP) servers
---
IronClaw connects to [Model Context Protocol](https://modelcontextprotocol.io/) servers, giving your agent access to external tools and data sources without writing custom integrations.
---
## Quickstart
```bash
# Add an HTTP server
ironclaw mcp add notion https://mcp.notion.com/mcp --client-id <your-client-id>
```
```bash
# Add a stdio server (spawns a local process)
ironclaw mcp add docs --transport stdio \
--command npx --arg @mintlify/mcp --arg=--docs --arg https://docs.ironclaw.com/mcp
```
```bash
# Add a Unix socket server
ironclaw mcp add myserver --transport unix --socket /tmp/mcp.sock
```
```bash
# Test connectivity
ironclaw mcp test notion
```
```bash
# List configured servers
ironclaw mcp list
```
```bash
# Remove a server
ironclaw mcp remove notion
```
```bash
# Toggle a server on/off
ironclaw mcp toggle notion
# Explicitly disable or enable
ironclaw mcp toggle notion --disable
ironclaw mcp toggle notion --enable
```
---
## Transports
| Transport | Use case | Example |
|--------------------|-------------------------------------------------------------------|-----------------------------------------------------------------------------|
| **HTTP** (default) | **Connects** to a remote server over HTTP(S) | `ironclaw mcp add name https://mcp.example.com` |
| **stdio** | **Spawns** a local server and **connects** to it via stdin/stdout | `ironclaw mcp add docs --transport stdio --command npx --arg @mintlify/mcp` |
| **Unix** | **Connects** to a server on a Unix domain socket | `ironclaw mcp add name --transport unix --socket /tmp/mcp.sock` |
### HTTP with OAuth
Many hosted MCP servers require OAuth 2.1 authentication. IronClaw implements the [MCP Authorization spec](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/authorization/) with PKCE:
```bash
# Add with OAuth credentials
ironclaw mcp add notion https://mcp.notion.com/mcp \
--client-id YOUR_CLIENT_ID \
--scopes "read,write"
# Authenticate (opens browser for consent)
ironclaw mcp auth notion
```
OAuth tokens are stored securely via IronClaw's secrets store and refreshed automatically.
### stdio with Environment Variables
Stdio servers often need API keys or configuration via environment variables:
```bash
ironclaw mcp add docs --transport stdio \
--command npx --arg @mintlify/mcp \
--env MINTLIFY_API_KEY=your_api_key
```
---
## Configuration File
Server configs are stored in `~/.ironclaw/mcp-servers.json`:
```json
{
"schema_version": 1,
"servers": [
{
"name": "docs",
"url": "",
"transport": {
"transport": "stdio",
"command": "npx",
"args": ["@mintlify/mcp", "--docs", "https://docs.ironclaw.com/mcp"]
},
"enabled": true,
"description": "IronClaw docs search"
},
{
"name": "notion",
"url": "https://mcp.notion.com/mcp",
"oauth": {
"client_id": "your-client-id",
"scopes": ["read", "write"]
},
"enabled": true
}
]
}
```
You can edit this file directly, or use `ironclaw mcp add` / `ironclaw mcp remove` to manage it.
---
## Custom Headers
For servers that use API key authentication instead of OAuth:
```bash
ironclaw mcp add myapi https://api.example.com/mcp \
--header "Authorization:Bearer sk-your-key" \
--header "X-Custom:value"
```
---
## Built-In Servers
IronClaw ships with a built-in registry of hosted MCP servers. A few examples:
| Server | Transport | What it does |
|------------------------------------------------|-----------|-------------------------------------------|
| [Asana](https://mcp.asana.com/v2/mcp) | HTTP | Task management, projects, and team coordination |
| [Cloudflare](https://mcp.cloudflare.com/mcp) | HTTP | DNS, Workers, KV, and infrastructure management |
| [Intercom](https://mcp.intercom.com/mcp) | HTTP | Customer messaging, support, and engagement |
| [Linear](https://mcp.linear.app/sse) | HTTP | Issue tracking and project management |
| [NEAR AI](https://private.near.ai/mcp) | HTTP | Built-in tools like web search |
| [Notion](https://mcp.notion.com/mcp) | HTTP | Pages, databases, and comments |
| [Sentry](https://mcp.sentry.dev/mcp) | HTTP | Error tracking and performance monitoring |
| [Stripe](https://mcp.stripe.com) | HTTP | Payments, subscriptions, and invoices |
Browse more servers at:
- [MCP Server Registry](https://github.com/modelcontextprotocol/servers) (official)
- [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) (community)
---
## Troubleshooting
```bash
# Check server health
ironclaw mcp test <server-name>
# Re-authenticate an OAuth server
ironclaw mcp auth <server-name>
# Disable without removing
ironclaw mcp toggle <server-name> --disable
# Debug logging
RUST_LOG=ironclaw::tools::mcp=debug ironclaw mcp test <server-name>
```

3
docs/docs.json
View File

@@ -74,7 +74,8 @@
]
},
"capabilities/skills",
"capabilities/sandboxed-tools"
"capabilities/sandboxed-tools",
"capabilities/mcp"
]
}
]