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

```bash theme={null}
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

```bash theme={null}
ironclaw mcp add weather https://mcp.weather.example.com
```

#### Add Server With OAuth

```bash theme={null}
ironclaw mcp add notion https://mcp.notion.com \
  --client-id YOUR_CLIENT_ID \
  --description "Notion workspace integration"
```

#### Add Server With Full OAuth Configuration

```bash theme={null}
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

```bash theme={null}
  ✓ 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

```bash theme={null}
ironclaw mcp remove <NAME>
```

### Arguments

**`<NAME>`**

Name of the server to remove.

### Examples

```bash theme={null}
ironclaw mcp remove notion
```

### Output

```bash theme={null}
  ✓ Removed MCP server 'notion'
```

***

## ironclaw mcp list

List all configured MCP servers.

### Syntax

```bash theme={null}
ironclaw mcp list [FLAGS]
```

### Flags

**`--verbose, -v`**

Show detailed information.

### Examples

```bash theme={null}
# List servers
ironclaw mcp list

# Show details
ironclaw mcp list --verbose
```

### Output

**Default output:**

```bash theme={null}
  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:**

```bash theme={null}
  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

```bash theme={null}
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

```bash theme={null}
# 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:

```bash theme={null}
╔════════════════════════════════════════════════════════════════╗
║                   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

```bash theme={null}
  Discovering OAuth endpoints...
  Registering client...
  Starting OAuth flow...
```

### Re-authentication

If already authenticated, you'll be prompted:

```bash theme={null}
  Server 'notion' is already authenticated.

  Re-authenticate? [y/N]: 
```

***

## ironclaw mcp test

Test connection to an MCP server and list available tools.

### Syntax

```bash theme={null}
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

```bash theme={null}
# Test connection
ironclaw mcp test notion

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

### Output

**Successful connection:**

```bash theme={null}
  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:**

```bash theme={null}
  Testing connection to 'notion'...
  ✗ Connection failed: HTTP 401 Unauthorized

  Run 'ironclaw mcp auth notion' to authenticate.
```

**Not authenticated:**

```bash theme={null}
  Testing connection to 'notion'...
  ✗ Not authenticated. Run 'ironclaw mcp auth notion' first.
```

***

## ironclaw mcp toggle

Enable or disable an MCP server.

### Syntax

```bash theme={null}
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

```bash theme={null}
# Toggle enabled/disabled state
ironclaw mcp toggle notion

# Explicitly enable
ironclaw mcp toggle notion --enable

# Explicitly disable
ironclaw mcp toggle notion --disable
```

### Output

```bash theme={null}
  ✓ Server 'notion' is now enabled.
```

or

```bash theme={null}
  ✓ 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`:

```json theme={null}
{
  "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

```bash theme={null}
ironclaw mcp add notion https://mcp.notion.com \
  --client-id YOUR_NOTION_CLIENT_ID
ironclaw mcp auth notion
```

### GitHub

```bash theme={null}
ironclaw mcp add github https://mcp.github.com \
  --client-id YOUR_GITHUB_CLIENT_ID \
  --scopes "repo,read:org"
ironclaw mcp auth github
```

### Slack

```bash theme={null}
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:

```bash theme={null}
ironclaw mcp list
```

Add the server if missing:

```bash theme={null}
ironclaw mcp add <name> <url>
```

### "SECRETS\_MASTER\_KEY not set"

Run onboarding to generate a master key:

```bash theme={null}
ironclaw onboard
```

Or set it manually in `.env`:

```bash theme={null}
SECRETS_MASTER_KEY=your-master-key
```

### "Authentication failed (token may be expired)"

Re-authenticate:

```bash theme={null}
ironclaw mcp auth <name>
```

### "OAuth client\_id not configured"

Add the server with a client ID:

```bash theme={null}
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](/cli/tool) - Manage WASM tools (alternative to MCP)
* [onboard](/cli/onboard) - Initial setup including secrets key
* [doctor](/cli/doctor) - Verify configuration