Setup Guide

Prerequisites

Before configuring the MCP server, you need:

1. A 1claw account — Sign up at 1claw.xyz
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).

Option 1: Hosted server (recommended)

The simplest setup — no local installation needed. The hosted MCP server runs at mcp.1claw.xyz 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

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

TypeScript

import { createClient } from "@1claw/sdk";

const client = createClient({
  baseUrl: "https://api.1claw.xyz",
  agentId: "<your-agent-uuid>",
  apiKey: "ocv_...",
});
// The SDK manages token exchange and refresh automatically.
// For manual token retrieval:
const { data } = await client.auth.agentToken({
  agent_id: "<your-agent-uuid>",
  api_key: "ocv_...",
});
console.log(data.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.xyz/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.xyz/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.xyz/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 ~1 hour).

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

Variable	Required	Default	Description
ONECLAW_AGENT_API_KEY	Yes* (stdio)	—	Agent API key (ocv_...). Server exchanges for JWT and auto-refreshes. Also auto-resolves agent ID and vault via prefix lookup.
ONECLAW_AGENT_ID	No	—	Agent UUID. Optional when using ONECLAW_AGENT_API_KEY (auto-resolved via prefix lookup).
ONECLAW_AGENT_TOKEN	Yes* (stdio)	—	Static JWT from POST /v1/auth/agent-token (alternative to API key; expires ~1 h).
ONECLAW_VAULT_ID	No	auto-discovered	UUID of the vault to operate on. When omitted, auto-discovered from the token exchange vault_ids or the first org vault.
ONECLAW_BASE_URL	No	https://api.1claw.xyz	Override for self-hosted vault

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

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