# Connect an AI agent

The vault is designed as a first-class control plane for AI agents. An agent gets the same policy-gated, audited, freezable access as any other machine user. This page shows the fastest ways to give a coding agent or LLM what it needs to use the vault.

## Security note

Give your agent the spec and the docs. Never give it key material. The vault is specifically designed so that private key material never leaves the MPC cluster; there is nothing to hand to an agent. The agent calls the API and the vault handles the signing.

## Option 1: hand the agent the raw OpenAPI spec

The spec is available at a well-known path with no authentication:

```
GET <your-vault-host>/openapi.json
GET <your-vault-host>/openapi.yaml
```

The spec documents all endpoints, request/response shapes, and the full Ed25519 transcript algorithm (in the `x-request-assertion` header description). An agent that reads the spec can construct valid signed requests without any additional guidance. Humans can browse the same endpoints in the interactive [API Reference](/api-reference).

Example system prompt addition:

```
You are a trading automation agent. To sign messages or manage keys, call the
Sodot Crypto Vault REST API. The full spec is at:
  https://<your-vault-host>/openapi.json

All mutating requests require four headers: authorization (ApiKey <uuid>),
x-request-nonce (16 hex chars of 8 random bytes), x-request-timestamp (16 hex
chars of a u64 LE millisecond timestamp), and x-request-assertion (base64url
Ed25519 signature over the SHA-256 transcript described in the spec).

Your API key is: ApiKey <uuid>
Your Ed25519 private key path is: /run/secrets/cv-private-key.pem
Never log or transmit the private key.
```

## Option 2: add the docs MCP server to Claude or Cursor

The vault docs expose an MCP server at `/api/mcp`. Adding it to your IDE or agent gives it indexed access to every page in this developer guide.

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "sodot-cv-docs": {
      "type": "http",
      "url": "https://<your-docs-host>/api/mcp"
    }
  }
}
```

### Cursor (`.cursor/mcp.json` in your project)

```json
{
  "mcpServers": {
    "sodot-cv-docs": {
      "type": "http",
      "url": "https://<your-docs-host>/api/mcp"
    }
  }
}
```

After adding the MCP server, restart the IDE. The agent can now search and read docs pages directly.

## Option 3: point the agent at `/llms.txt`

The docs publish an `/llms.txt` file with a structured map of every page and its description. This is useful for agents that prefer a lightweight index over a full MCP integration.

```
GET <your-docs-host>/llms.txt
```

## Example: agent prompt that builds a signed request

The following system prompt is enough for a capable code-generation agent to write correct signed requests from scratch, using only the spec as reference:

```
You are an API integration agent for the Sodot Crypto Vault.

Reference material:
- OpenAPI spec: https://<your-vault-host>/openapi.json
- Developer guide: https://<your-docs-host>/develop/authentication/machine-users

Authentication: every state-changing request requires four HTTP headers.
1. authorization: ApiKey <your-uuid>
2. x-request-nonce: 16-char lowercase hex of 8 cryptographically random bytes
3. x-request-timestamp: 16-char lowercase hex of current Unix time in ms,
   encoded as a u64 little-endian integer
4. x-request-assertion: base64url (no padding) of a 64-byte Ed25519 signature
   over the SHA-256 of the transcript

Transcript layout (binary):
  0x01 version byte
  for each of [method, path, query, body, apiKeyUuid]:
    4-byte LE uint32 length
    utf8 bytes
  8-byte LE uint64: timestamp in ms
  8 raw bytes: nonce

Strip "ApiKey " from the UUID when adding it to the transcript.
Sign the 32-byte SHA-256 digest (not the raw transcript) with the Ed25519 key.

When asked to sign a message, call POST /v1/keys/{key_id}/sign with body:
  {"message": "<payload>", "key_version": "Latest"}

The response is {"signature": "<string>"}.
```

## Granting the agent signing permission

An AI agent is a machine user in the vault. Create it the same way as any other machine user (see [Machine Users and Agents](/develop/authentication/machine-users)):

1. Generate an Ed25519 keypair for the agent.
2. Create a machine user in the vault with the agent's public key.
3. Add the machine user to a user group.
4. Configure the [Signing Policy](/api-reference#tag/signingpolicies) on the relevant [security group](/api-reference#tag/securitygroups) to approve requests from that user group.

The vault's policy, freeze, and audit controls apply to agent requests identically to human requests. You can restrict an agent to specific key sets and freeze the agent's signing ability at any time.