CyberSPF MCP server

Lets an MCP client — Claude Desktop, an editor, an agent framework — ask CyberSPF about an IP, a domain or an ASN, list what an account monitors, and pull the graded report card.

What it is, and what it deliberately is not

It runs on the customer's machine, over stdio, calling /api/v1/ over HTTPS with their own API key.

That shape is the design, not a shortcut:

• No new inbound surface. The droplet's only ingress stays the Cloudflare tunnel. A hosted MCP endpoint would add a second one.
• No new authentication. ClientAPIKeyAuthentication and HasApiAccess already gate v1. This is another client of them, not a new path in.
• No new metering. api_requests_per_day already counts these calls.
• Nothing to operate. A process the client starts and stops.

A hosted HTTP server is worth building if customers ask for one. It is not worth building first.

Requires

A plan that includes API access, and for cyberspf_report_card, a plan that includes the report card. Those are two separate entitlements and the server reports them differently — a key that works for lookups and is refused for the card is a plan limit, not a bad key.

Install

Nothing to install — uvx fetches and runs it:

uvx cyberspf-mcp

Or into an environment you manage:

pip install cyberspf-mcp

From a checkout, for development:

cd mcp_server
python -m venv .venv
. .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Configure

Create a key in CyberSPF under Settings → API keys, then point your client at the server. For Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "cyberspf": {
      "command": "uvx",
      "args": ["cyberspf-mcp"],
      "env": {
        "CYBERSPF_API_KEY": "your key here"
      }
    }
  }
}

That form exists because the alternative was two absolute paths. A client started from a desktop launcher inherits no PATH and no working directory, and a relative path there is the commonest reason a server appears in the client list and never answers. If uvx itself is not on the launcher's PATH, give its full path.

From a checkout instead, point command at the venv's python and args at server.py — both absolute, for the same reason.

Listing

server.json is the manifest for the official MCP Registry (registry.modelcontextprotocol.io), published as com.cyberspf/mcp. The registry namespaces by reverse DNS and verifies the domain, which is why the name is the one domain we can prove.

A stdio server is listed there through a packages entry naming a package registry and an identifier — so the PyPI package is a prerequisite for the listing, not merely a convenience.

CYBERSPF_BASE_URL overrides the endpoint; it defaults to https://cyberspf.com/api/v1. Useful for pointing at a staging host and for nothing else.

The tools

Three, not the eight the design sketch proposed. Two of those eight (zone_search and anything over new-domain data) have no data behind them — zone_domain holds zero rows since collection was paused — and the rest wrap endpoints v1 does not expose yet. Three that work beats eight where five return errors.

Following a result instead of stopping at it

cyberspf_lookup returns the API's own sections unflattened, on purpose. Values that can themselves be looked up carry a type (ip, domain, asn, cidr), so an agent can feed one back in:

look up example.com → take the addresses it resolves to → look each up → take the ASN announcing them → look that up

That chain is the point. Flattening the response into prose for the model would read more smoothly and would throw away the one field that makes the chain possible.

Failure messages

Every failure is phrased as something a person can act on, because an agent cannot read a stack trace and cannot retry its way out of a plan limit:

A blank term is refused locally rather than sent, so it does not spend one of the account's daily calls to be told it was blank.

Nothing here probes anything

Every tool reads what CyberSPF already stored. None of them causes a connection to the subject of the lookup, from the customer's machine or from ours — the report card in particular is built from stored data, which is what makes it safe for an agent to call in a loop. Outbound probing happens elsewhere in the product, from the dedicated prober, on its own schedule.