1claw-mcp

# @1claw/mcp

<!-- mcp-name: io.github.1clawAI/1claw-mcp -->

An MCP (Model Context Protocol) server that gives AI agents secure, just-in-time access to secrets stored in the [1claw](https://1claw.xyz) vault — and a standalone security inspection pipeline for detecting malicious LLM content. Secrets are fetched at runtime via the 1claw Agent API and never persisted in the LLM context window beyond the moment they are used.

**Local-only mode**: Run without vault credentials for security-only tools (e.g., `inspect_content`). Ideal for users running local models (Ollama, LM Studio, llama.cpp) who want prompt injection and threat detection without a 1claw account.

**Local daemon mode**: Connect to the local 1claw daemon instead of the cloud API. Secrets stay on your machine, injected into HTTP requests via a Unix socket proxy — the model never sees the raw value. Set `ONECLAW_LOCAL_VAULT=true` and optionally `ONECLAW_DAEMON_SOCKET`.

**API contract:** Vault-facing tools use the REST API described in [@1claw/openapi-spec](https://www.npmjs.com/package/@1claw/openapi-spec). LLM traffic through **Shroud** is not MCP — agents call `https://shroud.1claw.xyz` directly 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:

| Mode                | Use case                       | Auth                                                                 |
| ------------------- | ------------------------------ | -------------------------------------------------------------------- |
| **stdio** (default) | Local — Claude Desktop, Cursor | Env: `ONECLAW_AGENT_API_KEY` (recommended; auto-discovers agent + vault) or `ONECLAW_AGENT_ID` + key; or `ONECLAW_AGENT_TOKEN` + `ONECLAW_VAULT_ID` |
| **httpStream**      | Hosted at `mcp.1claw.xyz`      | Per-request headers: `Authorization: Bearer <token>`, `X-Vault-ID`   |

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.

## Installation (local / stdio)

### Homebrew (macOS / Linux)

```bash
brew install 1clawAI/tap/1claw-mcp
```

### From source

```bash
cd packages/mcp
pnpm install
pnpm run build
```

## Environment Variables

| Variable                  | Required       | Default                 | Description                                                                 |
| ------------------------- | -------------- | ----------------------- | --------------------------------------------------------------------------- |
| `ONECLAW_AGENT_API_KEY`   | stdio*         | —                       | **Recommended.** Agent API key (`ocv_...`). Server exchanges it for a JWT, auto-discovers agent ID and vault, and refreshes the token automatically. |
| `ONECLAW_LOCAL_ONLY`      | No             | `false`                 | Set to `true` for security-only mode (no vault credentials needed).         |
| `ONECLAW_LOCAL_VAULT`     | No             | `false`                 | Set to `true` to use the local daemon instead of the cloud API.             |
| `ONECLAW_DAEMON_SOCKET`   | No             | `~/.config/1claw/daemon.sock` | Path to the local daemon Unix socket (local daemon mode only).       |
| `ONECLAW_AGENT_ID`        | No             | —                       | Agent UUID. Optional with `ONECLAW_AGENT_API_KEY` (auto-discovered from key). |
| `ONECLAW_AGENT_TOKEN`     | stdio*         | —                       | **Legacy.** Static Bearer JWT (expires in ~1 h, no auto-refresh).          |
| `ONECLAW_VAULT_ID`        | No             | —                       | UUID of the vault. Auto-discovered when using `ONECLAW_AGENT_API_KEY`.     |
| `ONECLAW_DPOP`            | No             | `false`                 | Set to `true` to enable DPoP (RFC 9449) proof-of-possession. Binds agent tokens to the MCP client's ephemeral P-256 keypair so stolen tokens are unusable without the matching private key. |
| `ONECLAW_BASE_URL`        | No             | `https://api.1claw.xyz` | Vault API base URL. Intents tools (`simulate_transaction`, `submit_transaction`, etc.) call this host; for TEE signing, point it at **Shroud** or **Intents** (e.g. `https://shroud.1claw.xyz` or `https://intents.1claw.xyz`) if your deployment routes signing there. **Required when the agent has `intents_require_tee` or `execution_require_tee` enabled** — those flags reject direct Vault calls (403), so `ONECLAW_BASE_URL` must point to Shroud. Self-hosted: your Vault/Shroud URL. |
| `MCP_TRANSPORT`           | No             | `stdio`                 | Transport mode: `stdio` or `httpStream`.                                   |
| `PORT`                    | No             | `8080`                  | HTTP port (httpStream mode only).                                          |

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

| Tool                   | Description                                                                  |
| ---------------------- | ---------------------------------------------------------------------------- |
| `list_secrets`         | List all secrets (metadata only — never values)                              |
| `get_secret`           | Fetch the decrypted value of a secret by path. Accepts optional `client_share` for MPC vaults. |
| `put_secret`           | Create or update a secret (creates a new version). Response includes `client_share` when the vault has MPC enabled. |
| `delete_secret`        | Soft-delete a secret at a path                                               |
| `describe_secret`      | Get metadata without fetching the value                                      |
| `rotate_and_store`     | Store a new value for an existing secret and return the version              |
| `rotate_generate`      | Server-side secret rotation with generated value (length, charset configurable) |
| `list_versions`        | List all versions of a secret (version numbers, dates, disabled status)      |
| `get_env_bundle`       | Fetch an env_bundle secret and parse it as KEY=VALUE JSON                    |
| `create_vault`         | Create a new vault (auto-shared with the agent's human creator)              |
| `list_vaults`          | List all vaults the agent can access (own + shared)                          |
| `grant_access`         | Share a vault with a user or agent (own vaults only)                         |
| `share_secret`         | Share a secret with your creator, a user/agent by ID, or create an open link |
| `simulate_transaction` | Simulate a transaction via Tenderly without signing or broadcasting          |
| `simulate_bundle`      | Simulate an ordered sequence of transactions (Tenderly bundle) without signing |
| `submit_transaction`   | Submit a transaction intent to be signed and optionally broadcast (EVM + Bitcoin, Solana, XRP, Cardano, Tron). Auto-generates an `Idempotency-Key` header for replay protection. Supports `xrpl_tx_json` for 30+ XRPL transaction types (Payment, TrustSet, NFTokenMint, AMMCreate, EscrowCreate, etc.). |
| `sign_transaction`     | Sign-only (no broadcast). EVM returns `signed_tx` hex; non-EVM returns chain-specific signed payload. Supports `xrpl_tx_json` for arbitrary XRPL transactions. |
| `list_transactions`    | List transaction intents for the agent.                                      |
| `get_transaction`      | Get one transaction by id (optional `include_signed_tx`).                    |
| `provision_signing_key`| Generate a multi-chain signing key for an agent. Returns public key, address, and metadata. Private key stored securely in vault. |
| `list_signing_keys`    | List all signing keys for an agent across all chains.                        |
| `sign_message`         | Sign a message using EIP-191 personal_sign. Returns signature and signer address. |
| `sign_typed_data`      | Sign EIP-712 typed structured data. Returns signature, typed data hash, and signer address. |
| `sign_digest`          | Sign a client-computed 32-byte digest directly (raw/blind signing) for ERC-1271/ERC-7739 nested EIP-712 flows (e.g. Polymarket). Requires `raw_signing_enabled`; audit-logged. |
| `platform_list_apps`   | List all platform apps in the caller's org.                                                          |
| `platform_create_app`  | Register a new platform app (returns `plt_` API key). User-only.                                     |
| `platform_bootstrap_user` | Bootstrap resources (vault, agent, policies) for a connected user from a template.                |
| `platform_reissue_claim` | Reissue a claim URL for an already-bootstrapped connection without re-provisioning resources.       |
| `platform_rotate_key`  | Rotate the API key for a platform app. Returns the new `plt_` key (one-time).                        |
| `treasury_propose`     | Create a treasury multisig proposal (transaction intent for Safe signers to approve).                                    |
| `treasury_sign_proposal` | Sign or reject a treasury proposal. Submits an EIP-712 signature; auto-executes if threshold is met.                  |
| `treasury_list_proposals` | List proposals for a treasury, optionally filtered by status (pending, approved, executed, rejected, expired).        |
| `request_approval`     | Request human approval for a policy cha