pangolin-mcp (Pangolin MCP connector)

MCP connector for a self-hosted Pangolin Community Edition Integration API. It speaks that REST API over stdio and over stateless Streamable HTTP on localhost.

Pangolin Community Edition is AGPL-3.0 software. This connector is MIT. It only calls the public Integration REST API on the server you configure. It is not affiliated with Fossorial or Pangolin. Bring your own API key from your self-hosted instance (org-scoped or root).

This connector covers all 234 paths and 305 operations in pangolin.openapi.json (Pangolin CE 1.25.3). Operations are grouped into 20 toolsets. Enable a subset with PANGOLIN_TOOLSETS so the model only sees the tools you need.

Self-hosted Community Edition only. There is no default base URL. PANGOLIN_URL is required and must be your Integration API origin, for example https://api.example.com or http://127.0.0.1:3003. A trailing /v1 is stripped. Calls go to {PANGOLIN_URL}/v1. Hosts on pangolin.net are refused.

Setup

npm install
npm run ci
npm start
npm run start:http

npm start speaks stdio. npm run start:http serves Streamable HTTP at http://127.0.0.1:3000/mcp and GET /health. HTTP mode has no authentication. Keep it on localhost.

Create an API key in Pangolin (org API keys, or a root key on CE). The connector sends it as Authorization: Bearer and never prints it.

{
  "mcpServers": {
    "pangolin": {
      "command": "node",
      "args": ["/workspace/connectors/pangolin/dist/index.js"],
      "env": {
        "PANGOLIN_URL": "http://127.0.0.1:3003",
        "PANGOLIN_API_KEY": "...",
        "PANGOLIN_ALLOW_WRITES": "false",
        "PANGOLIN_TOOLSETS": "sites,resources,targets,roles,users,orgs",
        "PANGOLIN_CONTACT": "you@example.com"
      }
    }
  }
}

Docker (HTTP, no authentication, localhost only):

docker build -t pangolin-mcp .
docker run -p 3000:3000 \
  -e PANGOLIN_URL=http://host.docker.internal:3003 \
  -e PANGOLIN_API_KEY=... \
  pangolin-mcp

Do not put the API key in the image.

Regenerate the operations registry after an OpenAPI bump:

npm run gen:operations

Related MCP server: si.sigit/cli

Config

Safety

GET operations, and POST or PUT ops whose summaries are list or get, run without confirm. Every other write is gated.

A write needs confirm: true and PANGOLIN_ALLOW_WRITES=true. Otherwise the tool returns a dry-run preview of the method, path, query, and body. Secrets are redacted. Extra preview warnings cover public resource exposure, share links and access tokens, rules, targets, deletes of org, site, resource, user, role, client, domain, IdP, or API key, API key create and action grants, user invites, auth and bypass changes, certificate restart, and blueprint apply.

Pangolin wraps JSON in { data, success, error, message, status }. The connector returns data, message, and pagination. It never returns stack or server filesystem paths. Field names apiKey, secret, token, password, newtSecret, olmSecret, accessToken, clientSecret, and other secret/token/password/key names are redacted. Id fields such as apiKeyId and orgId are kept.

HTTP 401 means the key was rejected. HTTP 403 means the key does not have that action granted. HTTP 400 and 422 are validation errors. HTTP 429 includes Retry-After.

Tools

Default PANGOLIN_TOOLSETS publishes 6 tools. PANGOLIN_TOOLSETS=all publishes 20 tools (305 operations). Each tool takes action plus params, query, body, and optional confirm.

Example. List orgs, then create one after previewing:

{ "action": "list_orgs" }

{ "action": "create_org", "body": { "orgId": "lab", "name": "Lab", "subnet": "100.90.128.0/24", "utilitySubnet": "192.0.2.0/24" } }

{ "action": "create_org", "body": { "orgId": "lab", "name": "Lab", "subnet": "100.90.128.0/24", "utilitySubnet": "192.0.2.0/24" }, "confirm": true }

Live check

npm run live-check talks to a real Pangolin CE when PANGOLIN_URL and PANGOLIN_API_KEY are set. It lists orgs, creates a throwaway org (preview then confirm), then creates, reads, updates, and deletes a site, a role, and a public resource with a target where the CE API allows it. It lists users, domains, API keys, and logs, then deletes the org. If those variables are unset, it prints a skip message and exits 0.

LIVE-CHECK.md records the real run against Pangolin CE 1.25.3 built from source on the box.

Attribution

Pangolin is AGPL-3.0 (Community Edition). This connector is MIT and is not a derivative of Pangolin source. It is an independent HTTP client of the Integration API.

License

MIT, see LICENSE. This is an independent, unofficial connector and is not endorsed by the Pangolin project or its owners.

The upstream pangolin.openapi.json comes from a AGPL-3.0 project, so it is not shipped here. src/operations.ts was generated from it, and tests fall back to a route-only fixture in test/fixtures/. To regenerate, download the spec from the upstream project into the repo root (it is gitignored) and run node scripts/gen-operations.mjs.