@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.

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.

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.