packetfabric-mcp

MCP server for the PacketFabric API, built from its OpenAPI spec (346 operations, bundled in src/packetfabric_mcp/data/openapi.yaml).

Instead of one tool per endpoint (which overwhelms the model), it exposes 16 tools:

Safety

• Read-only by default. Any POST/PUT/PATCH/DELETE is refused unless the server runs with PF_ALLOW_WRITES=true.
• With writes enabled, a write call returns a dry-run preview first; it only executes when re-called with confirm=true.
• Auth/session, MFA, signup and API-key-management endpoints are never exposed.
• List responses are capped (max_items, default 100) and can be trimmed to specific fields.

Setup

Requires uv (brew install uv).

cd ~/Documents/src/packetfabric/mcp
uv sync
uv run pytest            # offline tests

Get an API key in the PacketFabric portal (Settings → API Keys). API keys work with MFA-enabled accounts; login/password does not.

Claude Code

claude mcp add packetfabric -s user -e PF_TOKEN=your-key -- \
  uv run --directory ~/Documents/src/packetfabric/mcp packetfabric-mcp

Claude Desktop / Cowork

Settings → Developer → Edit Config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "packetfabric": {
      "command": "/opt/homebrew/bin/uv",
      "args": ["run", "--directory", "/Users/chad/Documents/src/packetfabric/mcp", "packetfabric-mcp"],
      "env": { "PF_TOKEN": "your-key" }
    }
  }
}

(Use which uv for the command path. Restart Claude after editing.)

To allow provisioning, add "PF_ALLOW_WRITES": "true" to env. Consider a separate server entry (e.g. packetfabric-rw) so read-only stays the default.

Configuration

Hosted mode (MCP over HTTP + A2A + discovery)

uv sync --extra a2a
PF_PUBLIC_URL=https://mcp.example.com uv run packetfabric-mcp --http --host 0.0.0.0 --port 8765
# or: docker build -t packetfabric-mcp . && docker run -p 8765:8765 -e PF_PUBLIC_URL=... packetfabric-mcp

Every caller uses their own PacketFabric API key, sent as Authorization: Bearer <key> (plus On-Behalf: <customer uuid> for resellers). The operator's PF_TOKEN/PF_LOGIN are ignored in HTTP mode unless PF_HTTP_USE_SERVER_CREDENTIALS=true, which is only safe for a private single-user deployment. Put it behind TLS; the discovery documents are public by design and contain no secrets.

The A2A agent is deterministic, not an LLM: send a DataPart {"skill": "list_ports", "arguments": {"pop": "LAX1"}} and get the API result back as a JSON data artifact. Skills mirror the MCP tools (see the agent card). A2A access is always read-only.

curl -s https://mcp.example.com/a2a -H 'A2A-Version: 1.0' -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $PF_TOKEN" -d '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":
  {"messageId":"1","role":"ROLE_USER","parts":[{"data":{"skill":"find_locations","arguments":{"market":"NYC"}}}]}}}'

Domain-level discovery: if the server runs on its own host (e.g. mcp.packetfabric.com), the /.well-known/ documents are already in the right place. To advertise it from the main domain, serve a copy of /.well-known/ai-catalog.json from https://packetfabric.com/.well-known/ai-catalog.json (the entries hold absolute URLs, so a static copy works).

Publishing

Listed on the MCP Registry as io.github.PacketFabric/packetfabric-mcp (see server.json), installed from PyPI as packetfabric-mcp.

1. Bump the version in pyproject.toml, src/packetfabric_mcp/__init__.py and server.json (tests fail if they disagree).
2. Push a tag vX.Y.Z. .github/workflows/publish.yml runs the tests, publishes to PyPI (Trusted Publishing), then publishes server.json to the MCP Registry using GitHub OIDC.
3. Once the hosted server is live, set the repo variable MCP_PUBLIC_URL and the registry entry will also list it as a remote.

One-time: add a PyPI Trusted Publisher for packetfabric-mcp (repo PacketFabric/public-mcp, workflow publish.yml, environment pypi). The mcp-name: comment at the top of this README is how the registry verifies that the PyPI package belongs to this server; keep it.

To publish under com.packetfabric/... instead of io.github.PacketFabric/..., change REGISTRY_NAME in metadata.py and server.json, add the DNS TXT record from mcp-publisher login dns, and switch the workflow's login step.

Other

• Refresh the bundled spec: uv run packetfabric-mcp --update-spec
• To add a curated tool, copy one of the pf_list_* functions in server.py and point _run() at an operation_id (find one with pf_search_endpoints). Add a matching entry to SKILLS in a2a_agent.py.