ironclaw mcp

Manage Model Context Protocol (MCP) servers for hosted tool providers

ironclaw mcp

Manage MCP (Model Context Protocol) servers. MCP servers are hosted services that provide tools and capabilities to IronClaw through a standardized protocol.

Subcommands

• add - Add an MCP server
• remove - Remove an MCP server
• list - List configured MCP servers
• auth - Authenticate with an MCP server (OAuth flow)
• test - Test connection to an MCP server
• toggle - Enable or disable an MCP server

---

ironclaw mcp add

Add a new MCP server to your configuration.

Syntax

ironclaw mcp add <NAME> <URL> [FLAGS]

Arguments

<NAME>

Server name (e.g., notion, github, slack).

<URL>

Server URL (e.g., https://mcp.notion.com).

Flags

--client-id <ID>

OAuth client ID (if authentication is required).

--auth-url <URL>

OAuth authorization URL (optional, can be discovered).

--token-url <URL>

OAuth token URL (optional, can be discovered).

--scopes <SCOPES>

Comma-separated list of OAuth scopes to request.

--description <TEXT>

Server description.

Examples

Add Server Without Authentication

ironclaw mcp add weather https://mcp.weather.example.com

Add Server With OAuth

ironclaw mcp add notion https://mcp.notion.com \
  --client-id YOUR_CLIENT_ID \
  --description "Notion workspace integration"

Add Server With Full OAuth Configuration

ironclaw mcp add github https://mcp.github.com \
  --client-id YOUR_GITHUB_CLIENT_ID \
  --auth-url https://github.com/login/oauth/authorize \
  --token-url https://github.com/login/oauth/access_token \
  --scopes "repo,read:org" \
  --description "GitHub repository access"

Output

  ✓ Added MCP server 'notion'
    URL: https://mcp.notion.com

  Run 'ironclaw mcp auth notion' to authenticate.

---

ironclaw mcp remove

Remove an MCP server from your configuration.

Syntax

ironclaw mcp remove <NAME>

Arguments

<NAME>

Name of the server to remove.

Examples

ironclaw mcp remove notion

Output

  ✓ Removed MCP server 'notion'

---

ironclaw mcp list

List all configured MCP servers.

Syntax

ironclaw mcp list [FLAGS]

Flags

--verbose, -v

Show detailed information.

Examples

# List servers
ironclaw mcp list

# Show details
ironclaw mcp list --verbose

Output

Default output:

  Configured MCP servers:

  ● notion - https://mcp.notion.com (auth required)
  ● github - https://mcp.github.com (auth required)
  ○ weather - https://mcp.weather.example.com

  Use --verbose for more details.

Symbols:

• ● - Enabled server
• ○ - Disabled server

Verbose output:

  Configured MCP servers:

  ● notion (auth required)
      URL: https://mcp.notion.com
      Description: Notion workspace integration
      OAuth Client ID: oau_xxxxxxxxxxxxxxxxxxxxx
      Scopes: 

  ● github (auth required)
      URL: https://mcp.github.com
      Description: GitHub repository access
      OAuth Client ID: Iv1.xxxxxxxxxxxxxxxxxxxxx
      Scopes: repo, read:org

  ○ weather
      URL: https://mcp.weather.example.com
      Description: Weather data provider

---

ironclaw mcp auth

Authenticate with an MCP server using OAuth.

Syntax

ironclaw mcp auth <NAME> [FLAGS]

Arguments

<NAME>

Name of the server to authenticate with.

Flags

--user, -u <USER_ID>

User ID for storing the token.

• Default: default

Examples

# Authenticate with a server
ironclaw mcp auth notion

# Authenticate for specific user
ironclaw mcp auth notion --user alice

Interactive Flow

The command initiates an OAuth flow:

╔════════════════════════════════════════════════════════════════╗
║                   NOTION Authentication                        ║
╚════════════════════════════════════════════════════════════════╝

  Starting OAuth authentication...

  Opening browser for Notion login...

  Waiting for authorization...

  Exchanging code for token...

  ✓ Successfully authenticated with 'notion'!

  You can now use tools from this server.

Dynamic Client Registration (DCR)

If the server supports DCR and no client ID is configured, the command will:

1. Discover the server’s OAuth endpoints
2. Dynamically register a client
3. Use the registered client for authentication

  Discovering OAuth endpoints...
  Registering client...
  Starting OAuth flow...

Re-authentication

If already authenticated, you’ll be prompted:

  Server 'notion' is already authenticated.

  Re-authenticate? [y/N]: 

---

ironclaw mcp test

Test connection to an MCP server and list available tools.

Syntax

ironclaw mcp test <NAME> [FLAGS]

Arguments

<NAME>

Name of the server to test.

Flags

--user, -u <USER_ID>

User ID for authentication.

• Default: default

Examples

# Test connection
ironclaw mcp test notion

# Test with specific user credentials
ironclaw mcp test notion --user alice

Output

Successful connection:

  Testing connection to 'notion'...
  ✓ Connection successful!

  Available tools (5):
    • search_pages
      Search for pages in your Notion workspace
    • create_page
      Create a new page in a database
    • read_page
      Read the content of a page
    • update_page
      Update an existing page
    • query_database [approval required]
      Query a Notion database

Connection failure:

  Testing connection to 'notion'...
  ✗ Connection failed: HTTP 401 Unauthorized

  Run 'ironclaw mcp auth notion' to authenticate.

Not authenticated:

  Testing connection to 'notion'...
  ✗ Not authenticated. Run 'ironclaw mcp auth notion' first.

---

ironclaw mcp toggle

Enable or disable an MCP server.

Syntax

ironclaw mcp toggle <NAME> [FLAGS]

Arguments

<NAME>

Name of the server to toggle.

Flags

--enable

Enable the server.

--disable

Disable the server.

If neither flag is provided, the state is toggled.

Examples

# Toggle enabled/disabled state
ironclaw mcp toggle notion

# Explicitly enable
ironclaw mcp toggle notion --enable

# Explicitly disable
ironclaw mcp toggle notion --disable

Output

  ✓ Server 'notion' is now enabled.

or

  ✓ Server 'notion' is now disabled.

MCP Server Configuration Storage

MCP server configurations are stored in:

1. Database (if available) - mcp_servers table for user default
2. Disk fallback - ~/.ironclaw/mcp_servers.json

Configuration File Format

~/.ironclaw/mcp_servers.json:

{
  "servers": [
    {
      "name": "notion",
      "url": "https://mcp.notion.com",
      "description": "Notion workspace integration",
      "enabled": true,
      "oauth": {
        "client_id": "oau_xxxxxxxxxxxxxxxxxxxxx",
        "authorization_url": "https://api.notion.com/v1/oauth/authorize",
        "token_url": "https://api.notion.com/v1/oauth/token",
        "scopes": []
      }
    }
  ]
}

OAuth Token Storage

Access tokens are stored securely:

• Encrypted with SECRETS_MASTER_KEY
• Stored in the secrets table
• Named as mcp_<server_name>_access_token
• Refresh tokens stored as mcp_<server_name>_refresh_token

Common MCP Servers

Notion

ironclaw mcp add notion https://mcp.notion.com \
  --client-id YOUR_NOTION_CLIENT_ID
ironclaw mcp auth notion

GitHub

ironclaw mcp add github https://mcp.github.com \
  --client-id YOUR_GITHUB_CLIENT_ID \
  --scopes "repo,read:org"
ironclaw mcp auth github

Slack

ironclaw mcp add slack https://mcp.slack.com \
  --client-id YOUR_SLACK_CLIENT_ID \
  --scopes "channels:read,chat:write"
ironclaw mcp auth slack

Troubleshooting

”Server not found”

Check configured servers:

ironclaw mcp list

Add the server if missing:

ironclaw mcp add <name> <url>

“SECRETS_MASTER_KEY not set”

Run onboarding to generate a master key:

ironclaw onboard

Or set it manually in .env:

SECRETS_MASTER_KEY=your-master-key

“Authentication failed (token may be expired)”

Re-authenticate:

ironclaw mcp auth <name>

“OAuth client_id not configured”

Add the server with a client ID:

ironclaw mcp remove <name>
ironclaw mcp add <name> <url> --client-id YOUR_CLIENT_ID

“Server does not support OAuth authentication”

The server may:

• Not support OAuth
• Support a different authentication method
• Require Dynamic Client Registration (DCR) - happens automatically if supported

Related Commands

• tool - Manage WASM tools (alternative to MCP)
• onboard - Initial setup including secrets key
• doctor - Verify configuration