Skip to main content

MCP Integration

The 1claw MCP server gives AI agents (Claude, Cursor, GPT, and others) secure, just-in-time access to secrets stored in your vault via the Model Context Protocol.

Quick start (hosted)​

The fastest way to connect an AI agent to your vault:

  1. Register an agent in the 1claw dashboard — save the API key (ocv_...).
  2. Create a policy granting the agent read access to the paths it needs.
  3. Get a JWT by calling the agent-token endpoint with your agent ID and API key: 
    curl -s -X POST https://api.1claw.xyz/v1/auth/agent-token \
      -H "Content-Type: application/json" \
      -d '{"agent_id":"<uuid>","api_key":"ocv_..."}' | jq -r '.access_token'
  4. Configure your MCP client with the hosted server (use the JWT from step 3 as the Bearer token; it expires in ~1 hour):
{
  "mcpServers": {
    "1claw": {
      "url": "https://mcp.1claw.xyz/mcp",
      "headers": {
        "Authorization": "Bearer <jwt-from-agent-token-endpoint>",
        "X-Vault-ID": "your-vault-uuid"
      }
    }
  }
}

That's it. The agent can now call list_secrets, get_secret, and other tools.

Quick start (local)​

For local/air-gapped setups, run the MCP server via stdio. Use agent ID + API key so the server can refresh the JWT automatically:

cd packages/mcp && pnpm install && pnpm run build
{
  "mcpServers": {
    "1claw": {
      "command": "node",
      "args": ["/path/to/packages/mcp/dist/index.js"],
      "env": {
        "ONECLAW_AGENT_ID": "your-agent-uuid",
        "ONECLAW_AGENT_API_KEY": "ocv_your_agent_api_key",
        "ONECLAW_VAULT_ID": "your-vault-uuid"
      }
    }
  }
}

Available tools​

ToolWhat it does
list_secretsList all secrets (metadata only, never values)
get_secretFetch decrypted value by path
put_secretCreate or update a secret
delete_secretSoft-delete a secret
describe_secretGet metadata without the value
rotate_and_storeStore a new version of an existing secret
get_env_bundleFetch and parse a KEY=VALUE env bundle

Typical agent workflow​

  1. Discover — list_secrets to see what's available.
  2. Check — describe_secret to verify it exists and hasn't expired.
  3. Fetch — get_secret to get the decrypted value.
  4. Use — Pass the value into the API call.
  5. Forget — Do not store the value in summaries, logs, or memory.

Security​

  • Secrets are fetched just-in-time and never cached by the MCP server.
  • Secret values are never logged — only the path is recorded.
  • Each hosted connection authenticates independently (per-session isolation).
  • All access is recorded in the vault audit log.

Further reading​