ironclaw mcp - IronClaw

Overview

The ironclaw mcp command manages Model Context Protocol (MCP) servers. MCP servers are hosted tool providers that expose capabilities through a standardized API.

MCP allows you to connect to external services like Notion, GitHub, Slack, and more without installing separate tools.

Subcommands

add

Add a new MCP server:

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

string

required

Server name (e.g., “notion”, “github”).

string

required

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

string

OAuth client ID if authentication is required.

string

OAuth authorization URL (optional, can be discovered).

string

OAuth token URL (optional, can be discovered).

string

Comma-separated list of OAuth scopes to request.

string

Server description.

Examples:

# Add a server without authentication
ironclaw mcp add weather https://mcp.weather.example.com

# Add a server with OAuth
ironclaw mcp add notion https://mcp.notion.com \
  --client-id abc123 \
  --scopes "read:pages,write:pages" \
  --description "Notion workspace integration"

# Add with explicit OAuth endpoints
ironclaw mcp add github https://mcp.github.com \
  --client-id xyz789 \
  --auth-url https://github.com/login/oauth/authorize \
  --token-url https://github.com/login/oauth/access_token \
  --scopes "repo,read:user"

Output:

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

  Run 'ironclaw mcp auth notion' to authenticate.

remove

Remove an MCP server:

ironclaw mcp remove <NAME>

string

required

Server name to remove.

Example:

ironclaw mcp remove notion

Output:

  ✓ Removed MCP server 'notion'

list

List configured MCP servers:

ironclaw mcp list [OPTIONS]

flag

Show detailed information including OAuth configuration.

Example:

ironclaw mcp list
ironclaw mcp list --verbose

Output (normal):

  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.

Legend:

● - Enabled server
○ - Disabled server

Output (verbose):

  Configured MCP servers:

  ● notion (auth required)
      URL: https://mcp.notion.com
      Description: Notion workspace integration
      OAuth Client ID: abc123
      Scopes: read:pages, write:pages

  ● github (auth required)
      URL: https://mcp.github.com
      OAuth Client ID: xyz789
      Scopes: repo, read:user

  ○ weather
      URL: https://mcp.weather.example.com

auth

Authenticate with an MCP server using OAuth:

ironclaw mcp auth <NAME> [OPTIONS]

string

required

Server name to authenticate.

string

default:"default"

User ID for storing the token.

Example:

ironclaw mcp auth notion

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 you add a server without --client-id, IronClaw will attempt Dynamic Client Registration:

ironclaw mcp add notion https://mcp.notion.com
ironclaw mcp auth notion

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

  No OAuth configuration found, attempting Dynamic Client Registration...

  ✓ Client registered with Notion!

  Opening browser for login...

  ✓ Successfully authenticated with 'notion'!

Not all MCP servers support Dynamic Client Registration. If DCR fails, you’ll need to register your application manually and add the server with --client-id.

test

Test connection to an MCP server and list available tools:

ironclaw mcp test <NAME> [OPTIONS]

string

required

Server name to test.

string

default:"default"

User ID for authentication.

Example:

ironclaw mcp test notion

Output (success):

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

  Available tools (8):
    • notion_search [approval required]
      Search pages and databases in your Notion workspace
    • notion_create_page
      Create a new page in a database
    • notion_update_page
      Update properties of an existing page
    • notion_get_page
      Retrieve a page by ID
    • notion_list_databases
      List all databases in the workspace
    • notion_query_database [approval required]
      Query a database with filters and sorting
    • notion_create_database
      Create a new database
    • notion_get_user
      Get information about a user

Output (authentication required):

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

Output (connection failed):

  Testing connection to 'notion'...
  ✗ Connection failed: Connection refused (ECONNREFUSED)

toggle

Enable or disable an MCP server:

ironclaw mcp toggle <NAME> [OPTIONS]

string

required

Server name.

flag

Enable the server.

flag

Disable the server.

If neither --enable nor --disable is specified, the server state will be toggled.

Examples:

# Enable a server
ironclaw mcp toggle notion --enable

# Disable a server
ironclaw mcp toggle github --disable

# Toggle state
ironclaw mcp toggle weather

Output:

  ✓ Server 'notion' is now enabled.

Common MCP Servers

Popular MCP servers you can connect to:

Notion

ironclaw mcp add notion https://mcp.notion.com
ironclaw mcp auth notion

Tools: Search pages, create/update pages, query databases, manage workspaces.

GitHub

ironclaw mcp add github https://mcp.github.com \
  --scopes "repo,read:user,write:issues"
ironclaw mcp auth github

Tools: Create issues, manage PRs, search repositories, update files.

Slack

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

Tools: Send messages, list channels, manage conversations.

Google Drive

ironclaw mcp add gdrive https://mcp.google.com/drive \
  --scopes "https://www.googleapis.com/auth/drive.readonly"
ironclaw mcp auth gdrive

Tools: Search files, read documents, list folders.

Configuration Storage

MCP server configurations are stored in:

Database: If connected, stored in the mcp_servers table
Disk fallback: ~/.ironclaw/mcp_servers.json

Authentication tokens are stored securely in the secrets store (encrypted with your master key).

Troubleshooting

Authentication fails

If OAuth authentication fails:

Verify the server URL is correct
Check that your client_id is valid
Ensure you have the required scopes
Try re-authenticating: ironclaw mcp auth <name>
Check server logs for errors

Connection timeout

If ironclaw mcp test times out:

Check your internet connection
Verify the server URL is accessible
Check firewall rules
Try disabling VPN if applicable

Tools not appearing

If tools don’t show up after connecting:

Verify authentication: ironclaw mcp test <name>
Check server is enabled: ironclaw mcp list
Restart the agent: ironclaw run
Check agent logs for errors

Dynamic Client Registration fails

If DCR fails:

The server may not support DCR
Register your application manually on the provider’s website

Add the server with --client-id:

ironclaw mcp add notion https://mcp.notion.com --client-id YOUR_CLIENT_ID

ironclaw tool

Manage WASM tools

ironclaw status

View MCP server count

​Overview

​Subcommands

​add

​remove

​list

​auth

​test

​toggle

​Common MCP Servers

​Notion

​GitHub

​Slack

​Google Drive

​Configuration Storage

​Troubleshooting

​Related Commands

ironclaw tool

ironclaw status

Overview

Subcommands

add

remove

list

auth

test

toggle

Common MCP Servers

Notion

GitHub

Slack

Google Drive

Configuration Storage

Troubleshooting

Related Commands