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

* 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:

1. authenticates with the AGENT API key
2. derives and registers the runtime public key when the zero-trust SDK initializes
3. lists accessible vaults through the machine API
4. decrypts shared secrets locally on the runtime host
5. 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.