@rivet-dev/mcp

Rivet MCP

Rivet's Model Context Protocol server exposes Cloud discovery, actor operations, managed pool compute settings, Code Mode, and the embedded Rivet Actor Inspector app.

Run it locally against a RivetKit server:

pnpm rivet-mcp --target local --endpoint http://127.0.0.1:6420

Run it against Rivet Cloud by setting RIVET_CLOUD_TOKEN and selecting the organization, project, and namespace with CLI flags. The hosted OAuth endpoint is https://mcp.rivet.dev/mcp.

Choosing a target

The hosted endpoint serves one URL to every account, so a target is never stored for a session. Every tool that reads or writes Rivet state takes organization, project, and namespace arguments and acts on that target alone. Levels with a single option are filled in, so an account with one namespace needs no arguments. target_list reports the names when they are unknown.

?organization=, ?project=, and ?namespace= on the endpoint URL confine the session. A level the URL pins cannot be moved off: naming a different value for it fails with target/target_pinned, and the levels the URL leaves open still have to be named on each call. The pin is carried by the URL and not by the access token, so it confines the agent given that URL and is not a boundary against the token holder, who can drop the query and reach whatever the token's scopes allow.

Hosted writes need all three of rivet:cloud:write, rivet:actors:write, and rivet:inspector:write on the access token. Destructive operations are disabled on the hosted endpoint, and credential operations are never reachable from Code Mode.

Compute settings

rivet.cloud.managedPools.* reads and updates the compute deployment that hosts a namespace's actors, alongside rivet.cloud.metrics.compute for its usage and rivet.cloud.docker.* for the images it can run. These reach projects with Rivet Cloud compute enabled, and managedPools.upsert additionally needs rivet:cloud:write. Deleting a pool is not exposed.

Checking a build

scripts/harness-check.mjs exercises a built dist/ against a running Engine and exits non-zero if any check fails.

pnpm build
pnpm check:harness

The default pass drives the server over stdio JSON-RPC and asserts the Code Mode contract: implicit return values, globalThis.__return precedence, binding and upstream error messages surviving the isolate boundary, denied network access, and stdout staying separate from the result.

Add --agent to also run a headless Claude Code turn against the server, which bills the account and needs the claude CLI on PATH. That pass asserts the model reaches the same results writing ordinary JavaScript, and is the only check that covers how a real harness consumes the tools.

pnpm check:harness --agent

Point either pass at another Engine with --endpoint, --target, and --namespace.

To check a deployed endpoint instead of a local stdio process, pass --hosted-url. That mode adds the OAuth edge checks (/health, protected resource metadata, and the 401 bearer challenge), then mints a token through Authorization Code with PKCE and runs the same Code Mode contract over Streamable HTTP. Supply an existing token with --token to skip the sign-up and consent steps.

The hosted endpoint is namespace-scoped, so the pass provisions an organization, project, and namespace for the new account through the Cloud API before it connects. Point that at another deployment with --cloud-api.

just platform-up
pnpm check:harness --hosted-url http://localhost:48080/mcp

See the Rivet documentation under docs/general/mcp for setup, scopes, target selection, security limits, and deployment details.