fastly-mcp

A Node.js Model Context Protocol server for the Fastly REST API. It supports stdio and Streamable HTTP transports, tenant-scoped user or account identities, persistent Postgres configuration, and persistent Vault secrets.

Guarantees

• Every Fastly request uses the caller's user-scoped Fastly-Key; no shared Fastly token is configured in the process.
• Token material is written only to Vault at fastly/tenants/<tenant>/{users|accounts}/<principal>/http/auth/token-index/fastly.
• Non-secret configuration uses the Postgres table fastly_config, keyed by tenant, principal type, principal ID, and key.
• Mutations require MCP_ADMIN_AUTH_KEY through the authorizationKey tool parameter when that environment variable is set.
• service_api_request supports every documented Fastly method and path, including APIs added after this server release.

Tools

service_query_suggestion is read-only schema discovery. Use it when intent or the correct Fastly route is unclear; it returns recommended prerequisites, safety checks, tool schemas, and examples.

service_connection_info and service_scope_info are read-only runtime and tenant/account discovery tools. Use them before an operational workflow.

service_health_check calls GET /tokens/self with a user token. fastly_list_services calls GET /service. fastly_list_versions calls GET /service/:service_id/version.

service_api_request is the full-coverage escape hatch. It accepts method, path, optional query, body, headers, and required fastlyToken. GET/HEAD are read-only; POST/PUT/PATCH/DELETE are mutations and require authorizationKey when configured.

fastly_purge_service is high-risk and calls POST /service/:service_id/purge_all. Confirm the service ID and use the admin key. fastly_update_user_token is high-risk and persists a replacement token in Vault; provide exactly one of userId or accountId, plus tenantId, fastlyToken, and the admin key.

All responses contain JSON text shaped as { "ok": true, "status": 200, "data": {} }; failures set MCP isError and return { "ok": false, "status": 4xx, "error": "..." }. Secret-looking fields are redacted by default.

Configuration

Copy .env.example to .env. Set POSTGRES_*, VAULT_ADDR, VAULT_TOKEN or Vault Agent settings, and MCP_ADMIN_AUTH_KEY. TARGET_SERVICE_BASE_URL defaults to https://api.fastly.com. Use MCP_TRANSPORT_MODE=stdio, http, or both.

Run local dependencies with docker compose up -d postgres vault, then initialize Vault according to vault-production/README.md. Start the server with npm start, or use npm run start:http for HTTP. The HTTP endpoint defaults to http://127.0.0.1:3000/mcp and requires a bearer token.

External Services Mode

Use docker-compose.external.yml when Fastly MCP connects to external Vault and Postgres services. Set POSTGRES_HOST, VAULT_ADDR, and the corresponding credentials before starting the app-only Compose service.

Inventory and tests

npm run inventory:generate fetches Fastly's API reference index, or a JSON OpenAPI document supplied by FASTLY_OPENAPI_URL, and writes artifacts/fastly-openapi-endpoints.json. The artifact is committed and CI fails when generation changes it.

npm test runs the Fastly client, MCP authorization, persistence-supporting infrastructure, HTTP, and Vault tests. GitHub Actions runs inventory generation before the test job.

MCP client registration

{
  "mcpServers": {
    "fastly-mcp": {
      "command": "npm",
      "args": ["run", "start:stdio"],
      "cwd": "/Users/{user}/Documents/GitHub/fastly-mcp"
    }
  }
}

Development notes

The Fastly API uses TLS 1.2 or later and applies separate read, write, and purge limits. Avoid concurrent writes to the same service. Never log or commit fastlyToken values. This project is released under the MIT License; see LICENSE.