Skip to main content

Setup Guide

Prerequisites​

Before configuring the MCP server, you need:

  1. A 1claw account — Sign up at 1claw.co
  2. A vault — Create one from the dashboard
  3. An agent — Register an agent and save the API key (ocv_...)
  4. A policy — Grant the agent read access to the secret paths it needs
Try it out

Try out the example in this repo: FastMCP Tool Server (custom MCP server with domain tools; stdio or HTTP).

The simplest setup — no local installation needed. The hosted MCP server runs at mcp.1claw.co and authenticates per-connection with a Bearer JWT. You get the JWT by calling the 1claw API with your agent ID and API key (ocv_...):

curl -s -X POST https://api.1claw.co/v1/auth/agent-token \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"<your-agent-uuid>","api_key":"ocv_..."}' | jq -r '.access_token'

Use the returned access_token as the Bearer value below. The token expires in about an hour; for long-lived use, your client may need to refresh it by calling the agent-token endpoint again.

Claude Desktop​

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "1claw": {
      "url": "https://mcp.1claw.co/mcp",
      "headers": {
        "Authorization": "Bearer <jwt-from-agent-token-endpoint>",
        "X-Vault-ID": "your-vault-uuid-here"
      }
    }
  }
}

Cursor​

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "1claw": {
      "url": "https://mcp.1claw.co/mcp",
      "headers": {
        "Authorization": "Bearer <jwt-from-agent-token-endpoint>",
        "X-Vault-ID": "your-vault-uuid-here"
      }
    }
  }
}

Claude Code​

Claude Code uses the same MCP configuration as Cursor. Use either the hosted or local (stdio) config above (Cursor section). Then optionally install the 1claw skill so Claude knows when and how to use 1claw.

Any MCP client​

Any client that supports HTTP streaming can connect:

  • Endpoint: https://mcp.1claw.co/mcp
  • Headers: Authorization: Bearer <jwt> (from POST /v1/auth/agent-token with agent_id and api_key) and X-Vault-ID: <vault-uuid>

Option 2: Local server (stdio)​

Run the MCP server as a local process. Useful for development, air-gapped environments, or when you want full control. The server can use agent ID + API key (recommended; it exchanges them for a JWT and refreshes automatically) or a static JWT (expires in ~15 minutes by default).

Install​

cd packages/mcp
pnpm install
pnpm run build

Claude Desktop (recommended: agent ID + API key)​

{
  "mcpServers": {
    "1claw": {
      "command": "node",
      "args": ["/absolute/path/to/packages/mcp/dist/index.js"],
      "env": {
        "ONECLAW_AGENT_API_KEY": "ocv_your_agent_api_key"
      }
    }
  }
}

The server auto-discovers the agent ID and vault from the token exchange response. You can optionally set ONECLAW_AGENT_ID and ONECLAW_VAULT_ID for explicit control.

Cursor (recommended: agent ID + API key)​

{
  "mcpServers": {
    "1claw": {
      "command": "node",
      "args": ["./packages/mcp/dist/index.js"],
      "env": {
        "ONECLAW_AGENT_API_KEY": "${env:ONECLAW_AGENT_API_KEY}"
      }
    }
  }
}

Then set the environment variable in your shell:

export ONECLAW_AGENT_API_KEY="ocv_your_agent_api_key"

The server auto-resolves the agent ID via the API key prefix and auto-discovers the vault from the token exchange. To override, also set ONECLAW_AGENT_ID and/or ONECLAW_VAULT_ID.

Alternative (static JWT): If you prefer to pass a token yourself, set ONECLAW_AGENT_TOKEN to a JWT from POST /v1/auth/agent-token (with agent_id and api_key). The token expires in about an hour; you must refresh it manually.

Environment variables​

VariableRequiredDefaultDescription
ONECLAW_AGENT_API_KEYYes* (stdio)—Agent API key (ocv_...). Server exchanges for JWT and auto-refreshes. Also auto-resolves agent ID and vault via prefix lookup.
ONECLAW_AGENT_IDNo—Agent UUID. Optional when using ONECLAW_AGENT_API_KEY (auto-resolved via prefix lookup).
ONECLAW_AGENT_TOKENYes* (stdio)—Static JWT from POST /v1/auth/agent-token (alternative to API key; expires ~1 h).
ONECLAW_VAULT_IDNoauto-discoveredUUID of the vault to operate on. When omitted, auto-discovered from the token exchange vault_ids or the first org vault.
ONECLAW_BASE_URLNohttps://api.1claw.coOverride for self-hosted vault
ONECLAW_MCP_TOOLSETSNoentitlement defaultsComma list of toolsets to expose (or all). Narrows or opts in (automations, runtimes, chat, …); never widens past the agent's entitlements. Hosted: send X-1Claw-Toolsets instead. See Toolsets.

* Set ONECLAW_AGENT_API_KEY (recommended, simplest) or ONECLAW_AGENT_TOKEN + ONECLAW_VAULT_ID.

Narrower packages​

For stdio deployments where "this agent's MCP server cannot sign" must be true of the code on disk, two builds of the same server are published in lockstep:

PackageContainsNot in the package
@1claw/mcp-vaultvault + approvals toolsets, inspect_content, vault://secretssigning, execute, cards, memory, channels, chat, automations, runtimes, directory, platform, admin
@1claw/mcp-guardinspect_content only — no account, no credentialsany vault client at all

Swap @1claw/mcp for @1claw/mcp-vault (same env vars) or @1claw/mcp-guard (no env vars) in the args above.

Verifying the connection​

After configuration, ask your AI agent:

"List the secrets in my 1claw vault."

The agent should call list_secrets and return the paths and metadata of your secrets. If you get an authentication error, verify your agent credentials (agent ID + API key, or JWT) and vault ID.

Development tools​

# Interactive CLI testing
pnpm dev

# MCP Inspector (browser UI for testing tools)
pnpm inspect
Last updated on