Browse docs+

MCP

Use the official R4 MCP server when your agent framework already supports the Model Context Protocol.

This package is a local stdio MCP server. It keeps the private key on the runtime host and reuses the supported R4 zero-trust runtime flow.

Install

npm install -g @r4-sdk/mcp

You can also run it directly with npx:

npx -y @r4-sdk/mcp

Required Environment Variables

Variable	Required	Description
`R4_API_KEY`	Yes	AGENT API key in `{accessKey}.{secret}` format
`R4_PRIVATE_KEY_PATH`	Yes*	Absolute path to the local PEM-encoded RSA private key
`R4_PRIVATE_KEY`	Yes*	Inline PEM-encoded RSA private key
`R4_BASE_URL`	No	API base URL, defaults to `https://r4.dev`
`R4_PROJECT_ID`	No	Optional project filter
`R4_TRUST_STORE_PATH`	No	Optional trust-store JSON path

* Provide either R4_PRIVATE_KEY_PATH or R4_PRIVATE_KEY.

Example MCP Client Config

{
  "mcpServers": {
    "r4": {
      "command": "npx",
      "args": ["-y", "@r4-sdk/mcp"],
      "env": {
        "R4_API_KEY": "agent_access_key.secret",
        "R4_PRIVATE_KEY_PATH": "/absolute/path/to/agent-private-key.pem"
      }
    }
  }
}

What the MCP Server Does

The local MCP server:

authenticates with the AGENT API key
derives and registers the runtime public key when the zero-trust SDK initializes
lists accessible vaults through the machine API
decrypts shared secrets locally on the runtime host
exposes those capabilities as MCP tools

This is intentionally different from a hosted remote MCP server. The supported R4 runtime model keeps the RSA private key local to the machine that needs the secrets.

Available Tools

r4_auth_status — Validate config and summarize the visible runtime state
r4_list_vaults — List accessible vaults
r4_list_vault_items — List vault-item metadata without returning decrypted values
r4_search_secrets — Search exact secret keys by name without returning values
r4_get_secret — Return one decrypted secret value by exact key
r4_list_projects — List accessible projects
r4_get_project — Fetch one project detail payload
r4_machine_request — Call any authenticated machine API route directly when the higher-level tools do not cover the workflow yet

r4_get_secret is the sensitive tool. Prefer the metadata and search tools first so the client only requests secret values when it actually needs them. r4_machine_request may perform writes and may return sensitive machine payloads, so only use it when you truly need the raw route.

When to Use MCP

Choose MCP when:

your agent client already supports MCP
you want R4 exposed as tools instead of direct code imports
the runtime host can keep its private key locally

Choose the Node SDK when you want in-process access inside a Node app.

Choose the CLI when shell commands are the main integration surface.

If the MCP server is missing a capability you need and the current CLI, SDK, or raw machine API also does not cover it, submit product-gap feedback through POST /api/v1/machine/feedback with an AGENT API key. Do not include secrets or private user data in that payload.