@b1-road/mcp

Manage your Road platform from your AI coding agent — sign in, register a platform, issue credentials, wire webhooks — without opening the Dev Portal.

Built for the way people actually integrate with Road: describing what they want to an agent, rather than clicking through a dashboard.

Install

claude mcp add road --scope user -- npx -y -p @b1-road/mcp road-mcp

The -p @b1-road/mcp road-mcp form names the binary explicitly, which is what you want in a config that outlives this README. A bare npx @b1-road/mcp works too: the package publishes an mcp bin alias next to road-mcp and road-review, because the short form is what people type regardless of what the docs say. Before that alias it exited with "could not determine executable to run" — if you see that error you are on an older version.

(The alias means a global npm i -g @b1-road/mcp puts an mcp command on your PATH. MCP servers are normally launched by the host through npx, so a global install is unusual — but if you do one and already have another mcp, use road-mcp.)

--scope user makes it available in every project, which is usually what you want — your Road account is not repo-specific. Use --scope project instead to write a .mcp.json your whole team shares.

Then, in your agent:

Sign me in to Road

What it can do

| Area | Tools | | --- | --- | | Session | road_login, road_login_status, road_whoami, road_logout, road_onboard_account | | Platforms | road_list_platforms, road_get_platform, road_register_platform, road_set_operational_metadata, road_activate_platform, road_archive_platform, road_platform_status | | Permissions & roles | road_get_permissions_and_roles, road_set_permissions_and_roles | | Sign-in credentials | road_issue_credentials, road_get_credentials, road_update_redirect_uris, road_rotate_platform_secret with kind='signin', road_revoke_credentials | | Bridge service credential (M2M) | road_issue_service_credential, road_rotate_platform_secret with kind='bridge-service', road_revoke_service_credential | | Webhooks | road_list_webhooks, road_register_webhook, road_update_webhook, road_rotate_webhook_secret, road_delete_webhook, road_webhook_test_event, road_webhook_delivery_log | | Platform Bridge | road_list_bridge_providers, road_request_connection, road_list_connection_requests, road_revoke_connection_request | | Contract intake | road_submit_contract, road_get_contract_submissions | | Extensions (author) | road_list_extension_targets, road_register_extension, road_list_extensions, road_update_extension, road_submit_extension, road_rotate_extension_secret, road_provision_extension_identity, road_get_extension_identity, road_revoke_extension_identity | | Extension points (provider) | road_declare_extension_point, road_list_extension_points, road_update_extension_point, road_deprecate_extension_point | | Knowledge | road_overview, road_guide | | Security | road_security_review |

Start with road_platform_status when something is not working — it reports what a platform still needs, whether credentials are issued, and whether webhooks are registered.

Explaining, not just doing

road_overview and road_guide(topic) answer what Eduzz Plat is and how each part of an integration works — sign-in, permissions, webhooks, going live, troubleshooting, and what your app has to look like. They need no account, no platform and no credentials, so an agent can read them before there is anything to act on. The same pages are exposed as MCP resources (road://concepts, road://guide/<topic>) for clients that let you @-mention one.

The content is authored once in the Road monorepo and rendered into this package at build time. The @b1-road/integrate skill ships the same pages, so the two cannot drift apart. There is no separate docs site.

Checking it is safe to ship

road_security_review runs a catalog of known-consequence misconfigurations against a platform: wildcard or plaintext redirect URIs, tunnel hosts left registered, papéis with unbounded reach, a webhook route that never verifies a signature, a secret behind a browser-exposed prefix, a client id that no longer matches the credential.

It is read-only, it calls no host you did not register, and it is not a pentest. A check that could not run reports não sei rather than a pass, and the summary reports counts rather than a score. road_guide('security') lists the whole catalog, rendered from the same definitions the review executes — so the page and the check cannot describe different rules.

It does not block anything. road_activate_platform names any unresolved critical findings in its own output and activates regardless.

In CI, without an agent

The same catalog runs headless:

npx -p @b1-road/mcp road-review <platformId>
npx -p @b1-road/mcp road-review <platformId> --baseline .road-security-baseline.json

Exit 0 when nothing serious is unresolved, 1 on unresolved critical or high findings — or, with --baseline, only on findings the baseline did not have, so a project with existing findings can adopt it without a red build on day one. Exit 2 means the review could not run, which is deliberately distinct from finding something.

Waive a check in .road-security-ignore, one per line, with a reason:

A3 — the tunnel is intentional while the demo is up

The reason is required. A waived check keeps the state it evaluated to and stays in the report marked as waived, because "waived and still failing" is the case worth seeing.

Signing in

Two steps, because the sign-in happens in your browser while the agent waits:

1. road_login returns immediately with a link (and opens your browser).
2. Sign in, then road_login_status completes it.

The session is cached at ~/.config/road/mcp-<env>.json (mode 0600) and refreshes itself, so you sign in once per machine rather than once per day.

Over SSH, in a devcontainer, or in a Codespace there is no local browser to redirect to, so the server switches to a device code you enter on another machine — road_login shows the code, and road_login_status finishes as before. Force either mode with ROAD_AUTH_FLOW=device or ROAD_AUTH_FLOW=loopback.

Secrets

Secrets are never returned in tool output. When Road issues a client secret or a webhook signing secret — which it reveals exactly once — this server writes it straight into your .env and tells you the file path.

That is deliberate: anything a tool returns goes into your conversation history, which is stored, often synced, and easy to paste somewhere public by accident. A secret that never enters the transcript cannot leak from it.

Each webhook's signing secret gets its own key (ROAD_WEBHOOK_SECRET_<WEBHOOK_ID>), because a platform can hold several endpoints and Road reveals each secret only once.

When a value is replaced, the old one is removed, not commented out — a commented secret is still readable in backups, cloud sync, or an accidental commit, and rotation exists so the previous value stops working. The file is forced to 0600 on every write, including a .env that already existed with looser permissions.

⚠️ Add .env to your own repository's .gitignore before issuing credentials. These secrets are written into the repository you run the agent in, and this package's .gitignore does not cover it. 0600 controls who can read the file locally; it does nothing to stop git add . from committing it.

Configuration

| Variable | Purpose | | --- | --- | | ROAD_ENV | sandbox (default) or production. Selects the API, the Auth Server and the OIDC client in one go — nothing else to set. | | ROAD_API_URL | Road API origin. Set with ROAD_ISSUER + ROAD_CLIENT_ID to target your own instance. | | ROAD_ISSUER | Auth Server issuer. | | ROAD_CLIENT_ID | OIDC client id for this MCP server. | | ROAD_AUTH_FLOW | loopback or device. Auto-detected when unset. | | ROAD_NO_BROWSER | Set to 1 to stop road_login opening a browser. The sign-in link is still returned — paste it wherever you like. |

ROAD_API_URL, ROAD_ISSUER and ROAD_CLIENT_ID are all-or-nothing: setting only some of them is an error that names the ones you missed, rather than quietly falling back to ROAD_ENV — otherwise a typo points the server at the default environment while looking like your override worked.

Development

npm install
npm run typecheck
npm test
npm run build

To try a local build against a Road environment:

npm run build
claude mcp add road-dev -- node "$PWD/dist/server.mjs"