@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 session can read by default and can write with --allow-write. Cloud calls stay inside that organization, so projects and namespaces can only be created there. 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.

Projects and namespaces

On Rivet Cloud, rivet.cloud.projects.create and rivet.cloud.namespaces.create need rivet:cloud:write and a writable target. A connection pinned to a project cannot create projects, and one pinned to a namespace cannot create namespaces. A new project comes with a namespace displayed as Production, whose name carries a random suffix like every name the Cloud API generates. Creates are not idempotent. A failure after the request may have reached the Cloud API (a timeout, a dropped connection, an upstream 5xx, or an unreadable success response) throws cloud/create_indeterminate, and the caller should list before retrying. Deleting either is not exposed.

On a local or self-hosted engine, rivet.namespaces.list and rivet.namespaces.create manage the engine's own namespaces and need a writable target to create one. The caller picks the name, which must be 1 to 64 lowercase letters, digits, and single hyphens. Creating a name that already exists fails with namespace/name_not_unique, so retrying is safe. The session stays on the namespace it was started with. A session with Rivet Cloud gets rivet.cloud.* and no rivet.namespaces.*, and one without Cloud gets the reverse, in both search and execute. Cloud creates are listed only when the session has write access and no pinned level rules them out.

On the hosted endpoint, execute runs with only an organization, or an organization and project, named, so these calls do not need an existing namespace. Engine, actor, and inspector calls still do.

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.

Runner configs

rivet.runnerConfigs.list and rivet.runnerConfigs.upsert manage the active namespace's engine runner configs, on Rivet Cloud and on a local or self-hosted engine alike, and rivet.datacenters.list names the datacenters they are keyed by. Upserts need a writable target, plus rivet:cloud:write on Rivet Cloud. The engine deletes a config from any datacenter an upsert leaves out, so an upsert must name every datacenter or pass one config for all of them. Deleting a runner config is not exposed. A runner config owned by a Rivet Cloud managed pool (metadata.provider of rivet) cannot be changed from MCP and is refused with runner_config/managed_pool.

Telemetry

The published CLI reports crashes to Rivet's Sentry so failures on real installs are visible. Reports carry the error, its stack, the package version, and the target kind. Known credential environment variables are stripped from every event before it is sent.

Opt out with either of:

export DO_NOT_TRACK=1
export RIVET_MCP_TELEMETRY=0

Product analytics is never enabled by a locally run CLI. The embedded Inspector app reports to PostHog only when the hosted server at https://mcp.rivet.dev/mcp serves it, since telemetry configuration is injected into the bundle by whichever server hands it to the MCP host.

It shares the dashboard's PostHog project. The sandboxed iframe cannot persist a distinct id, so every open is a new anonymous user; all events carry surface: "mcp-inspector-app" so dashboard metrics can exclude them.

MCP hosts render the app from an origin they own and enforce the CSP the app declares, which allows only the server that served it. Both vendors are relayed through that same origin rather than declared as third-party domains:

• POST /mcp/telemetry/sentry tunnels Sentry envelopes. Envelopes naming any DSN other than the configured one are refused, so it cannot act as an open relay.
• /mcp/telemetry/posthog/* reverse-proxies PostHog.

The CLI mounts both on its loopback inspector proxy; the hosted server mounts them under MCP_PUBLIC_URL.

Both surfaces report under the Sentry release rivet-mcp@<version>. The npm name is not usable there because Sentry rejects slashes in a release version. Sourcemaps are uploaded by the publish workflow when SENTRY_AUTH_TOKEN is configured, and the release publishes normally when that upload fails.

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.

pnpm check:harness --hosted-url https://your-deployment.example.com/mcp

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