Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt

Use this file to discover all available pages before exploring further.

​
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
  • tool - Manage WASM tools (alternative to MCP)
  • onboard - Initial setup including secrets key
  • doctor - Verify configuration

Build docs developers (and LLMs) love

Get started for freeTalk to us