@r4-sdk/mcp

Official R4 MCP server for local agent runtimes. It wraps the existing zero-trust R4 SDK and machine API so MCP clients can:

• verify local R4 auth/setup
• inspect the current machine principal, tenant binding, and capability constraints
• list accessible vaults
• inspect vault-item metadata
• search secret names
• retrieve a specific decrypted secret value
• inspect accessible project metadata
• call arbitrary authenticated machine API routes when the higher-level tools do not cover a workflow

This package is intentionally a local stdio MCP server. It keeps the RSA private key on the agent host and uses the existing AGENT API key + local private key runtime flow.

Install

npm install -g @r4-sdk/mcp

You can also run it without a global install:

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; use instead of R4_PRIVATE_KEY_PATH when needed | | R4_BASE_URL | No | API base URL, defaults to https://r4.dev | | R4_PROJECT_ID | No | Optional project filter for vault access | | R4_TRUST_STORE_PATH | No | Optional path to the local trust-store JSON |

* 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"
      }
    }
  }
}

Available Tools

• r4_auth_status — Validate the current R4 MCP configuration and return vault/secret counts plus machine scope/context/capabilities
• r4_list_vaults — List accessible vaults
• r4_list_vault_items — List vault-item metadata across one vault or all visible vaults
• r4_search_secrets — Search decrypted 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 — Get one project's detail payload
• r4_machine_request — Call any authenticated machine API route; this may perform writes and may return sensitive machine payloads

r4_machine_request is the escape hatch for newer headless features. Prefer the specialized tools first when they already express the workflow you need.

Development

pnpm run build
pnpm run test
pnpm run test:pack