> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onefirewall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# v2026-06-22 - MCP Server

> Connect AI agents directly to OneFirewall threat intelligence and firewall automation via the Model Context Protocol

The **OneFirewall MCP Server** exposes OneFirewall's threat intelligence platform to AI agents — Claude, GPT-4, Copilot, and any MCP-compatible client — as callable tools. Agents can investigate IPs, pull live threat feeds, report malicious actors, and query firewall agent status without leaving the conversation.

***

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that lets AI models call external tools over a secure, structured interface. Instead of copy-pasting IPs into a dashboard, an AI agent can call `get_ip_intel("1.2.3.4")` and receive structured threat intelligence directly in its context.

***

## Connect Your AI Tool

The OneFirewall MCP server is hosted and managed for you. Your JWT token is available from the [OneFirewall dashboard](https://app.onefirewall.com). Paste it into the configuration for your AI client below.

<Tabs>
  <Tab title="Claude Desktop">
    Edit `claude_desktop_config.json`:

    **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\
    **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

    ```json theme={null}
    {
      "mcpServers": {
        "onefirewall": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://mcp.onefirewall.com/mcp",
            "--header", "Authorization: Bearer YOUR_JWT_TOKEN"
          ]
        }
      }
    }
    ```

    Restart Claude Desktop. The OneFirewall tools appear in the tools panel (hammer icon).
  </Tab>

  <Tab title="Cursor">
    Open **Cursor Settings → MCP** and add a new server, or edit `.cursor/mcp.json` in your project:

    ```json theme={null}
    {
      "mcpServers": {
        "onefirewall": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://mcp.onefirewall.com/mcp",
            "--header", "Authorization: Bearer YOUR_JWT_TOKEN"
          ]
        }
      }
    }
    ```

    The tools become available in Cursor's Agent mode automatically.
  </Tab>

  <Tab title="Windsurf">
    Edit `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "onefirewall": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://mcp.onefirewall.com/mcp",
            "--header", "Authorization: Bearer YOUR_JWT_TOKEN"
          ]
        }
      }
    }
    ```

    Reload Windsurf. Tools are available in Cascade (Agent mode).
  </Tab>

  <Tab title="VS Code (GitHub Copilot)">
    Add to your VS Code `settings.json`:

    ```json theme={null}
    {
      "mcp": {
        "servers": {
          "onefirewall": {
            "type": "http",
            "url": "https://mcp.onefirewall.com/mcp",
            "headers": {
              "Authorization": "Bearer YOUR_JWT_TOKEN"
            }
          }
        }
      }
    }
    ```

    Enable **GitHub Copilot Agent mode** and the OneFirewall tools will be listed under available MCP servers.
  </Tab>

  <Tab title="Claude Code (CLI)">
    Run once to register the server globally:

    ```bash theme={null}
    claude mcp add --transport http onefirewall https://mcp.onefirewall.com/mcp \
      --header "Authorization: Bearer YOUR_JWT_TOKEN"
    ```

    The tools are then available in every Claude Code session without further configuration.
  </Tab>

  <Tab title="OpenCode">
    Add to `~/.config/opencode/config.json`:

    ```json theme={null}
    {
      "mcp": {
        "onefirewall": {
          "type": "remote",
          "url": "https://mcp.onefirewall.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_JWT_TOKEN"
          }
        }
      }
    }
    ```

    The OneFirewall tools will be available automatically in your next OpenCode session.
  </Tab>
</Tabs>

***

## Available Tools

<CardGroup cols={2}>
  <Card title="get_ip_intel" icon="shield-halved">
    Full CTI profile for an IPv4 — crime score, MITRE ATT\&CK mappings, STIX2 bundles, member reports, and attack observations.
  </Card>

  <Card title="get_live_ipv4_feeds" icon="list">
    Paginated real-time feed of all malicious IPs above a configurable crime score threshold. Ready for firewall/IPS ingestion.
  </Card>

  <Card title="report_ip" icon="flag">
    Submit threat intelligence on a malicious IP to the OneFirewall Alliance, contributing to the collective crime score.
  </Card>

  <Card title="get_agent_status" icon="server">
    Status, configuration, active blocklist, and last sync time for all WCF firewall agents in your organisation.
  </Card>
</CardGroup>

***

## Tool Reference

### `get_ip_intel`

Retrieve the complete intelligence profile for an IPv4 address.

| Parameter | Type   | Required | Description                                              |
| --------- | ------ | -------- | -------------------------------------------------------- |
| `ipv4`    | string | Yes      | The IPv4 address to investigate (e.g. `"185.220.101.5"`) |

**Example prompt:**

> *"What does OneFirewall know about 185.220.101.5?"*

**Returns:** crime score, MITRE ATT\&CK techniques, STIX2 bundles, number of Alliance members who reported it, agent observations, geolocation, ASN, and historical notes.

***

### `get_live_ipv4_feeds`

Pull a real-time blocklist of malicious IPs above a minimum crime score.

| Parameter    | Type    | Required | Default | Description                                        |
| ------------ | ------- | -------- | ------- | -------------------------------------------------- |
| `min_score`  | integer | Yes      | —       | Minimum WCF crime score (1–1000)                   |
| `format`     | string  | No       | `CSV`   | `CSV` or `LIST` (comma-separated)                  |
| `show_score` | string  | No       | —       | `"yes"` to include score alongside each IP         |
| `page`       | string  | No       | —       | Pagination cursor from `next_page` response header |
| `agid`       | string  | No       | —       | Scope feed to a specific WCF Agent ID              |
| `plugin`     | string  | No       | —       | Filter by IPS/plugin name                          |

**Example prompt:**

> *"Give me all IPs with a crime score above 200 in CSV format."*

<Note>
  Responses are paginated. If the `next_page` header is present in the API response, pass that value as the `page` parameter to retrieve the next batch.
</Note>

***

### `report_ip`

Report an IP address as malicious to the OneFirewall Alliance.

| Parameter    | Type    | Required | Default | Description                                              |
| ------------ | ------- | -------- | ------- | -------------------------------------------------------- |
| `ip`         | string  | Yes      | —       | IPv4 address or CIDR network                             |
| `confidence` | float   | Yes      | —       | Confidence level: `0.0` (uncertain) → `1.0` (certain)    |
| `source`     | string  | Yes      | —       | Where the threat was observed (e.g. `"sshlog"`, `"ids"`) |
| `notes`      | string  | No       | —       | Free-text description of the observed behaviour          |
| `decision`   | integer | No       | `-1`    | `-1` = score-based, `0` = whitelist, `1` = blacklist     |
| `ttl`        | integer | No       | —       | Unix timestamp after which the decision override expires |

**Example prompt:**

> *"Report 10.0.0.1 as malicious — I observed repeated SSH brute-force attempts, confidence 0.95, source 'sshlog'."*

***

### `get_agent_status`

Retrieve the status of WCF firewall agents registered in your organisation.

| Parameter | Type   | Required | Description                                                      |
| --------- | ------ | -------- | ---------------------------------------------------------------- |
| `agid`    | string | No       | Agent ID to filter to a single agent. Omit to return all agents. |

**Example prompt:**

> *"Show me the status of all my firewall agents."*

**Returns:** per-agent configuration (score threshold, sync interval, max rules), last sync timestamp, active blocklist, plugin name, and error codes.