Skip to main content

​
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]
​
name
string
required
Server name (e.g., “notion”, “github”).
​
url
string
required
Server URL (e.g., “https://mcp.notion.com”).
​
--client-id
string
OAuth client ID if authentication is required.
​
--auth-url
string
OAuth authorization URL (optional, can be discovered).
​
--token-url
string
OAuth token URL (optional, can be discovered).
​
--scopes
string
Comma-separated list of OAuth scopes to request.
​
--description
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>
​
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]
​
-v, --verbose
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]
​
name
string
required
Server name to authenticate.
​
-u, --user
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]
​
name
string
required
Server name to test.
​
-u, --user
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]
​
name
string
required
Server name.
​
--enable
flag
Enable the server.
​
--disable
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

If OAuth authentication fails:
  1. Verify the server URL is correct
  2. Check that your client_id is valid
  3. Ensure you have the required scopes
  4. Try re-authenticating: ironclaw mcp auth <name>
  5. Check server logs for errors
If ironclaw mcp test times out:
  1. Check your internet connection
  2. Verify the server URL is accessible
  3. Check firewall rules
  4. Try disabling VPN if applicable
If tools don’t show up after connecting:
  1. Verify authentication: ironclaw mcp test <name>
  2. Check server is enabled: ironclaw mcp list
  3. Restart the agent: ironclaw run
  4. Check agent logs for errors
If DCR fails:
  1. The server may not support DCR
  2. Register your application manually on the provider’s website
  3. 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