
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 theteramoby/speedle-sdkdesign 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 checkregisters onlyis_allowedby default and reads only ADS configuration. The other read-only authorization tools require the explicit opt-ins documented below.npx @speedle/mcp manageregisters only the policy management tools and reads only PMS configuration.manage --read-onlyregisters only its read tools.- There is no default mode that exposes both. Running
speedle-mcpwithout a mode prints usage and exits with a non-zero status. - Never grant
managemode 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
managemode to an agent that is itself governed by the policies in this Speedle instance. Such an agent could be prompted into granting itself access. Runmanageonly for a human-supervised policy author, and prefer--read-onlywhen 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
managemode to an agent that is itself governed by the policies in this Speedle account or service; apms:writeAPI 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:readallows the read tools. Pair it with--read-only(orSPEEDLE_PMS_READ_ONLY=true) so the write tools are not registered at all.pms:writeallows every tool, including creates and deletes.adsAPI keys answer authorization checks only; the management API rejects them with403 insufficient_scope.
Cloud notes:
- A Cloud API key covers the account. In
managemode,list_serviceslists the account's services, the other tools takeserviceNameto select one of them per call, andcreate_servicetakesnamefor the new service. An unknown service returns404 not_found. Incheckmode,SPEEDLE_SERVICE_NAMEselects the service for the server; an unknown service returns404 service_not_found(or403 service_mismatchon older Cloud deployments). create_servicereturns409 service_existswhen 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
429withRetry-After; the tool result includesretryAfterand, when the server sends it,quotaDailyRemaining.
Environment Variables (check mode)
| Variable | Required | Description |
|---|---|---|
SPEEDLE_ENDPOINT (or SPEEDLE_ADS_ENDPOINT / SPEEDLE_ADS_URL) | Yes | ADS base URL, e.g. https://cloud.speedle.io or http://127.0.0.1:6734. |
SPEEDLE_SERVICE_NAME (or SPEEDLE_SERVICE) | Yes | Service 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 Cloud | Optional 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_BACKEND | No | "speedle-cloud" or "speedle". Defaults to "speedle-cloud" when SPEEDLE_TOKEN is configured and "speedle" otherwise. |
SPEEDLE_ALLOW_INSECURE_HTTP | No | Set to "true" to allow plaintext http:// to non-loopback hosts on speedle without an API key or bearer token. |
SPEEDLE_CA_CERT | No | Extra PEM CA certificate for self-hosted https:// servers. |
SPEEDLE_EXPOSE_DIAGNOSE | No | Set to "true" or "1" to register diagnose (same as --expose-diagnose). Self-hosted Speedle ("speedle") only. |
SPEEDLE_EXPOSE_ALL_GRANTED_ROLES | No | Set to "true" or "1" to register all_granted_roles (same as --expose-all-granted-roles). |
SPEEDLE_EXPOSE_ALL_GRANTED_PERMISSIONS | No | Set 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-diagnoseorSPEEDLE_EXPOSE_DIAGNOSE. Returns{ allowed, reason, requestContext?, attributes?, grantedRoles?, rolePolicies?, policies? }. Available only on self-hostedspeedle; refused onspeedle-cloud.all_granted_roles(POST /authz-check/v1/all-granted-roles): Opt in with--expose-all-granted-rolesorSPEEDLE_EXPOSE_ALL_GRANTED_ROLES. Returns thestring[]array of granted role names.all_granted_permissions(POST /authz-check/v1/all-granted-permissions): Opt in with--expose-all-granted-permissionsorSPEEDLE_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 foris_allowedanddiagnose; optional forall_granted_rolesandall_granted_permissions).action: Action string (required foris_allowedanddiagnose; optional forall_granted_rolesandall_granted_permissions).attributes: Optional request attributes in either:- Typed array form:
[{ name, type: "string" | "numeric" | "bool" | "datetime", value }], wherevalueis a single value or array of that type (datetimevalues are RFC 3339 strings with an explicit time zone, such as"2026-11-05T03:00:00Z"). - Inferred object form:
{ [name]: value }where strings becomestring(even if they look like dates), numbers becomenumeric, booleans becomebool, and non-empty homogeneous arrays use the corresponding type, sorted by Unicode code point.
- Typed array form:
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.
| Variable | Required | Description |
|---|---|---|
SPEEDLE_PMS_ENDPOINT | Yes | PMS 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_BACKEND | No | "speedle-cloud" or "speedle" (default, self-hosted PMS). Unlike check mode, SPEEDLE_PMS_TOKEN alone does not select Cloud. |
SPEEDLE_PMS_TOKEN | Speedle Cloud | API 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_KEY | No | PEM client certificate and private key for mutual TLS. The key is never logged or echoed. |
SPEEDLE_PMS_ALLOW_INSECURE_HTTP | No | Set to "true" to allow plaintext http:// to non-loopback hosts without credentials. |
SPEEDLE_PMS_CA_CERT | No | Extra PEM CA certificate for self-hosted https:// servers. |
SPEEDLE_PMS_READ_ONLY | No | Set 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 theglobalservice, 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 returns409 service_existswhen the service already exists or the account has reached its service limit.create_policy,create_role_policy:POST /service/{serviceName}/policyor/role-policyfrom 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 MCPdestructiveHintannotation and requireconfirmto equal the target'sserviceName,policyIdorrolePolicyId. A missing or differentconfirmfails 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.
create_service {"name":"books"}returns{"changed":"created","kind":"service","service":{"name":"books","type":"application",...}}.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.create_policywith"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}.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"}}.create_role_policy {"serviceName":"books","name":"alice-is-librarian","spdl":"grant user alice librarian"}returns the role policy with its ID.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"}],...}.delete_policy {"serviceName":"books","policyId":"zfcic2a7fyjknvtzjhfz","confirm":"books"}fails withConfirmationErrorand sends nothing. With"confirm":"zfcic2a7fyjknvtzjhfz"it returns{"changed":"deleted","kind":"policy","policy":{...}}.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.
@speedle/mcpnpm install @speedle/mcp@speedle/mcpnpm install @speedle/mcp