Repository avatar
Security
v1.9.0
active

speedle-mcp

io.github.teramoby/speedle-mcp

MCP server for self-hosted Speedle and Speedle Cloud: authorization checks and policy management

Documentation

@speedle/mcp

Local stdio Model Context Protocol (MCP) server for self-hosted Speedle and Speedle Cloud: authorization checks (check mode) and policy management (manage mode). See the Speedle documentation and Speedle AI MCP overview.

Requirements & Install

Requires Node.js >= 22.

npm install @speedle/mcp

Or run directly with npx:

npx @speedle/mcp check

The MCP Registry name is io.github.teramoby/speedle-mcp (server.json). check and manage are separate package entries, one mode at a time.

Note: The shared HTTP client in src/core (used by both modes) follows the teramoby/speedle-sdk design specification (typed attributes, error model, and retry policy). A future release may replace it with @speedle/sdk.

Security: Why Two Modes in One Package

Authorization checks are read-only queries and are typically wired into an AI agent whose actions Speedle governs. Policy management writes policy. An agent that holds both tool sets could be prompted into granting itself access.

To enforce separation of privilege:

  • npx @speedle/mcp check registers only is_allowed by default and reads only ADS configuration. The other read-only authorization tools require the explicit opt-ins documented below.
  • npx @speedle/mcp manage registers only the policy management tools and reads only PMS configuration. manage --read-only registers only its read tools.
  • There is no default mode that exposes both. Running speedle-mcp without a mode prints usage and exits with a non-zero status.
  • Never grant manage mode to an agent that is itself governed by the policies in that Speedle service.
  • Check tools only answer authorization questions; they do not enforce access control on their own.

Report security issues privately using the Speedle security policy.

MCP Client Configuration

check mode — Self-hosted Speedle (loopback or internal ADS)

{
  "mcpServers": {
    "speedle-check": {
      "command": "npx",
      "args": ["-y", "@speedle/mcp", "check"],
      "env": {
        "SPEEDLE_ENDPOINT": "http://127.0.0.1:6734",
        "SPEEDLE_SERVICE_NAME": "books"
      }
    }
  }
}

check mode — Speedle Cloud (sign-in opens soon)

{
  "mcpServers": {
    "speedle-check": {
      "command": "npx",
      "args": ["-y", "@speedle/mcp", "check"],
      "env": {
        "SPEEDLE_ENDPOINT": "https://cloud.speedle.io",
        "SPEEDLE_SERVICE_NAME": "books",
        "SPEEDLE_TOKEN": "spdl_..."
      }
    }
  }
}

Speedle Cloud sign-in opens soon; the spdl_… API key becomes available then.

check mode — Additional self-hosted tools

The following example opts in to all three additional tools. Each flag is independent; omit any tool that the agent does not need. diagnose returns detailed policy evaluation output and is intended for trusted operators.

{
  "mcpServers": {
    "speedle-check": {
      "command": "npx",
      "args": [
        "-y",
        "@speedle/mcp",
        "check",
        "--expose-diagnose",
        "--expose-all-granted-roles",
        "--expose-all-granted-permissions"
      ],
      "env": {
        "SPEEDLE_ENDPOINT": "http://127.0.0.1:6734",
        "SPEEDLE_SERVICE_NAME": "books"
      }
    }
  }
}

The equivalent environment variables are SPEEDLE_EXPOSE_DIAGNOSE, SPEEDLE_EXPOSE_ALL_GRANTED_ROLES, and SPEEDLE_EXPOSE_ALL_GRANTED_PERMISSIONS, each set to "true" or "1". diagnose is available only with backend "speedle"; configuring it with speedle-cloud fails at startup.

manage mode — Self-hosted Speedle Policy Management (PMS)

Security: never give manage mode to an agent that is itself governed by the policies in this Speedle instance. Such an agent could be prompted into granting itself access. Run manage only for a human-supervised policy author, and prefer --read-only when the agent only needs to read policies.

{
  "mcpServers": {
    "speedle-manage": {
      "command": "npx",
      "args": ["-y", "@speedle/mcp", "manage"],
      "env": {
        "SPEEDLE_PMS_ENDPOINT": "http://127.0.0.1:6733"
      }
    }
  }
}

For a read-only policy reviewer, use "args": ["-y", "@speedle/mcp", "manage", "--read-only"] or set SPEEDLE_PMS_READ_ONLY to "true".

manage mode — Speedle Cloud

Security: the warning above applies here too. Never give manage mode to an agent that is itself governed by the policies in this Speedle account or service; a pms:write API key can change those policies, including the agent's own access.

Speedle Cloud exposes the same PMS-compatible API at https://cloud.speedle.io/policy-mgmt/v1, so manage mode uses the same tools. Select the backend explicitly; an API key alone does not switch the mode away from a self-hosted PMS.

{
  "mcpServers": {
    "speedle-manage": {
      "command": "npx",
      "args": ["-y", "@speedle/mcp", "manage", "--read-only"],
      "env": {
        "SPEEDLE_PMS_ENDPOINT": "https://cloud.speedle.io",
        "SPEEDLE_PMS_BACKEND": "speedle-cloud",
        "SPEEDLE_PMS_TOKEN": "spdl_..."
      }
    }
  }
}

Sign-in opens soon; once you can sign in, create an API key in the Speedle Cloud console under API keys and choose its scope:

  • pms:read allows the read tools. Pair it with --read-only (or SPEEDLE_PMS_READ_ONLY=true) so the write tools are not registered at all.
  • pms:write allows every tool, including creates and deletes.
  • ads API keys answer authorization checks only; the management API rejects them with 403 insufficient_scope.

Cloud notes:

  • A Cloud API key covers the account. In manage mode, list_services lists the account's services, the other tools take serviceName to select one of them per call, and create_service takes name for the new service. An unknown service returns 404 not_found. In check mode, SPEEDLE_SERVICE_NAME selects the service for the server; an unknown service returns 404 service_not_found (or 403 service_mismatch on older Cloud deployments).
  • create_service returns 409 service_exists when the service already exists or the account has reached its service limit.
  • Every management request counts toward the account's daily PMS + ADS quota. A burst or daily-quota limit returns 429 with Retry-After; the tool result includes retryAfter and, when the server sends it, quotaDailyRemaining.

Environment Variables (check mode)

VariableRequiredDescription
SPEEDLE_ENDPOINT (or SPEEDLE_ADS_ENDPOINT / SPEEDLE_ADS_URL)YesADS base URL, e.g. https://cloud.speedle.io or http://127.0.0.1:6734.
SPEEDLE_SERVICE_NAME (or SPEEDLE_SERVICE)YesService name sent on every check request. Cannot be overridden by tool callers. On Speedle Cloud, selects a service in the API key's account.
SPEEDLE_TOKEN (or SPEEDLE_ADS_TOKEN)Speedle CloudOptional API key (spdl_…, sent as a bearer token; env var name kept for compatibility). Requires https://. Never logged or echoed in tool output or errors.
SPEEDLE_BACKENDNo"speedle-cloud" or "speedle". Defaults to "speedle-cloud" when SPEEDLE_TOKEN is configured and "speedle" otherwise.
SPEEDLE_ALLOW_INSECURE_HTTPNoSet to "true" to allow plaintext http:// to non-loopback hosts on speedle without an API key or bearer token.
SPEEDLE_CA_CERTNoExtra PEM CA certificate for self-hosted https:// servers.
SPEEDLE_EXPOSE_DIAGNOSENoSet to "true" or "1" to register diagnose (same as --expose-diagnose). Self-hosted Speedle ("speedle") only.
SPEEDLE_EXPOSE_ALL_GRANTED_ROLESNoSet to "true" or "1" to register all_granted_roles (same as --expose-all-granted-roles).
SPEEDLE_EXPOSE_ALL_GRANTED_PERMISSIONSNoSet to "true" or "1" to register all_granted_permissions (same as --expose-all-granted-permissions).

Tools (check mode)

Registered tools query /authz-check/v1/* on the configured ADS endpoint using serviceName from environment configuration:

  • is_allowed (POST /authz-check/v1/is-allowed): Registered by default. Returns { allowed, reason, errorMessage?, quotaDailyRemaining? }.
  • diagnose (POST /authz-check/v1/diagnose): Opt in with --expose-diagnose or SPEEDLE_EXPOSE_DIAGNOSE. Returns { allowed, reason, requestContext?, attributes?, grantedRoles?, rolePolicies?, policies? }. Available only on self-hosted speedle; refused on speedle-cloud.
  • all_granted_roles (POST /authz-check/v1/all-granted-roles): Opt in with --expose-all-granted-roles or SPEEDLE_EXPOSE_ALL_GRANTED_ROLES. Returns the string[] array of granted role names.
  • all_granted_permissions (POST /authz-check/v1/all-granted-permissions): Opt in with --expose-all-granted-permissions or SPEEDLE_EXPOSE_ALL_GRANTED_PERMISSIONS. Returns [{ resource, actions }].

Tool Inputs

  • subject: A user name string (e.g. "alice", shorthand for [{ type: "user", name: "alice" }]) or a non-empty list of principals { type?: "user" | "group" | "role" | "entity", name: string, idd?: string }.
  • resource: Resource string (required for is_allowed and diagnose; optional for all_granted_roles and all_granted_permissions).
  • action: Action string (required for is_allowed and diagnose; optional for all_granted_roles and all_granted_permissions).
  • attributes: Optional request attributes in either:
    • Typed array form: [{ name, type: "string" | "numeric" | "bool" | "datetime", value }], where value is a single value or array of that type (datetime values are RFC 3339 strings with an explicit time zone, such as "2026-11-05T03:00:00Z").
    • Inferred object form: { [name]: value } where strings become string (even if they look like dates), numbers become numeric, booleans become bool, and non-empty homogeneous arrays use the corresponding type, sorted by Unicode code point.

Environment Variables (manage mode)

manage mode reads only these variables. It never reads SPEEDLE_ENDPOINT, SPEEDLE_SERVICE_NAME, SPEEDLE_TOKEN or any other ADS variable.

VariableRequiredDescription
SPEEDLE_PMS_ENDPOINTYesPMS or Speedle Cloud base URL, e.g. http://127.0.0.1:6733 or https://cloud.speedle.io. A trailing /policy-mgmt/v1 is accepted.
SPEEDLE_PMS_BACKENDNo"speedle-cloud" or "speedle" (default, self-hosted PMS). Unlike check mode, SPEEDLE_PMS_TOKEN alone does not select Cloud.
SPEEDLE_PMS_TOKENSpeedle CloudAPI key (sent as a bearer token; env var name kept for compatibility). Required for "speedle-cloud", where it needs the pms:read or pms:write scope. Requires https://. Never logged or echoed in tool output or errors.
SPEEDLE_PMS_CERT / SPEEDLE_PMS_KEYNoPEM client certificate and private key for mutual TLS. The key is never logged or echoed.
SPEEDLE_PMS_ALLOW_INSECURE_HTTPNoSet to "true" to allow plaintext http:// to non-loopback hosts without credentials.
SPEEDLE_PMS_CA_CERTNoExtra PEM CA certificate for self-hosted https:// servers.
SPEEDLE_PMS_READ_ONLYNoSet to "true" to register only the read tools (same as --read-only).

Tools (manage mode)

All tools call the Speedle PMS REST API (/policy-mgmt/v1, see api/swagger/policy-manage.yaml in teramoby/speedle-plus), which both a self-hosted PMS and Speedle Cloud implement. Every service-scoped tool takes serviceName (or name for create_service) as an input argument, so a single manage server can manage any service in a self-hosted PMS or in the Speedle Cloud account. Policies and role policies are returned with an spdl field that renders them as one SPDL statement (or null when SPDL cannot express them).

Read tools (registered in every manage run):

  • list_services, get_service: GET /service, GET /service/{serviceName}.
  • list_policies, get_policy: GET /service/{serviceName}/policy[/{policyId}].
  • list_role_policies, get_role_policy: GET /service/{serviceName}/role-policy[/{rolePolicyId}].
  • show_effective_policies: every policy and role policy Speedle evaluates for a service, as SPDL: the service's own policies and role policies plus the role policies of the global service, which apply to every service.

Write tools (not registered with --read-only); each returns what changed:

  • create_service: POST /service; returns the created service. On Speedle Cloud this returns 409 service_exists when the service already exists or the account has reached its service limit.
  • create_policy, create_role_policy: POST /service/{serviceName}/policy or /role-policy from one SPDL statement (spdl) or a structured body; returns the created policy with its ID. Creates are sent once and never retried.

PMS validates every policy on create, and it is authoritative. There is no separate SPDL validation tool, because PMS has no validation endpoint and a local validator could disagree with it. spdl is converted to the PMS JSON body by a TypeScript port of the speedle-plus pkg/pdl parser (src/manage/spdl.ts). It rejects the statements that parser rejects, with the same message and position, before anything is sent; the condition after if is checked by PMS. A differential test keeps the port in step with the Go parser (see test/fixtures/spdl/README.md).

  • delete_service, delete_policy, delete_role_policy: carry the MCP destructiveHint annotation and require confirm to equal the target's serviceName, policyId or rolePolicyId. A missing or different confirm fails without sending any request. They return the deleted object as it was before the delete.

The PMS bulk deletes (DELETE /service, DELETE /service/{serviceName}/policy, /role-policy), functions and discover requests are not exposed.

Policy-Design Walkthrough

This session was run against a local Speedle PMS built from source (teramoby/speedle-plus 52f1bc7, speedle-pms --store-type file --insecure=true) through speedle-mcp manage. Responses are shortened.

  1. create_service {"name":"books"} returns {"changed":"created","kind":"service","service":{"name":"books","type":"application",...}}.
  2. create_policy {"serviceName":"books","name":"librarians-edit-books","spdl":"grant librarian get /books/*"} fails with {"error":"SpdlError","message":"Not found principal type (user|group|role|entity)\ngrant librarian get /books/*\n ^"} and sends nothing. The principal needs a type.
  3. create_policy with "spdl":"grant role librarian get,write /books/* if hour <" reaches PMS, which rejects the condition: {"error":"InvalidRequestError","message":"HTTP 400: SPDL-0004 policy \"librarians-edit-books\": invalid condition at character 7: Unexpected end of expression\nhour <\n ^","status":400}.
  4. create_policy {"serviceName":"books","name":"librarians-edit-books","spdl":"grant role librarian get,write /books/* if hour < 18"} returns {"changed":"created","kind":"policy","serviceName":"books","policy":{"id":"zfcic2a7fyjknvtzjhfz",...,"condition":"hour < 18",...,"spdl":"grant role librarian get,write /books/* if hour < 18"}}.
  5. create_role_policy {"serviceName":"books","name":"alice-is-librarian","spdl":"grant user alice librarian"} returns the role policy with its ID.
  6. show_effective_policies {"serviceName":"books"} returns {"counts":{"policies":1,"rolePolicies":1,"globalRolePolicies":0},"policies":[{"id":"zfcic2a7fyjknvtzjhfz","name":"librarians-edit-books","spdl":"grant role librarian get,write /books/* if hour < 18"}],"rolePolicies":[{"id":"32cruluw4kforfpgfvjq","name":"alice-is-librarian","spdl":"grant user alice librarian"}],...}.
  7. delete_policy {"serviceName":"books","policyId":"zfcic2a7fyjknvtzjhfz","confirm":"books"} fails with ConfirmationError and sends nothing. With "confirm":"zfcic2a7fyjknvtzjhfz" it returns {"changed":"deleted","kind":"policy","policy":{...}}.
  8. delete_service {"serviceName":"books","confirm":"books"} returns {"changed":"deleted","deletedPolicies":0,"deletedRolePolicies":1,"service":{...}}.

Development & Testing

npm ci
npm run lint          # ESLint + Prettier check + TypeScript typecheck
npm test              # Unit and security tests against a mock HTTP server
npm run test:package  # Build, npm pack, and smoke test the packed binary

Pull request review

Opening or updating an open, non-draft pull request from this repository starts a ReviewBot review. ReviewBot reads the diff and does not run pull-request code. Collaborators with write access can request another pass by commenting on the pull request:

@reviewbot review
@reviewbot recheck
@reviewbot explain why does this tool read that environment variable?

See ReviewBot.

Running the Local Speedle Integration Test

test/integration.test.ts builds speedle-ads and speedle-pms from a local checkout of teramoby/speedle-plus (requires Go) and starts each on a free loopback port against a temporary file store. The check test verifies the default registration, then opts in to and exercises all four check tools over stdio. The manage test creates a service, creates a policy and a role policy (and checks that PMS rejects an invalid condition), lists them, shows the effective policies, refuses a delete with the wrong confirmation, deletes with the right one, and deletes the service. When SPEEDLE_DIR is unset (and SPEEDLE_ADS_BIN / SPEEDLE_PMS_BIN are unset), the tests are skipped, including in CI.

SPEEDLE_DIR=/path/to/speedle-plus npm run test:integration

License

UPL-1.0. Copyright (c) 2026 The Speedle Authors.

NPM
@speedle/mcp
Install Command
npm install @speedle/mcp
Runtime: npx
NPM
@speedle/mcp
Install Command
npm install @speedle/mcp
Runtime: npx