ironclaw/docs/capabilities/mcp.md

title, description

title	description
Model Context Protocol (MCP)	Connect your agent to Model Context Protocol (MCP) servers

IronClaw connects to Model Context Protocol servers, giving your agent access to external tools and data sources without writing custom integrations.

---

Quickstart

# Add an HTTP server
ironclaw mcp add notion https://mcp.notion.com/mcp --client-id <your-client-id>

# 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

# Add a Unix socket server
ironclaw mcp add myserver --transport unix --socket /tmp/mcp.sock

# Test connectivity
ironclaw mcp test notion

# List configured servers
ironclaw mcp list

# Remove a server
ironclaw mcp remove notion

# 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 with PKCE:

# 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:

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:

{
  "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:

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	HTTP	Task management, projects, and team coordination
Cloudflare	HTTP	DNS, Workers, KV, and infrastructure management
Intercom	HTTP	Customer messaging, support, and engagement
Linear	HTTP	Issue tracking and project management
NEAR AI	HTTP	Built-in tools like web search
Notion	HTTP	Pages, databases, and comments
Sentry	HTTP	Error tracking and performance monitoring
Stripe	HTTP	Payments, subscriptions, and invoices

Browse more servers at:

• MCP Server Registry (official)
• awesome-mcp-servers (community)

---

Troubleshooting

# 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>