# AI agents

seekrit speaks [MCP](https://modelcontextprotocol.io) through **two servers**, split
along the zero-knowledge line:

- **Hosted metadata server** — `mcp.seekrit.dev`. An agent authenticates *itself*
  (no human, no browser) and can explore and provision structure (orgs, apps,
  environments, groups, composition), read audit and billing, and manage keyless
  resources. No install.
- **Local crypto server** — `npx -y @seekrit/mcp` (or `seekrit mcp` if you already
  have the [CLI](/docs/reference/cli)). Runs on the agent's machine and does
  everything that touches a secret *value*: set/read secrets, create environments,
  mint and grant tokens, and run commands with secrets injected.

**One credential drives both.** An agent signs up once for a machine credential
(a client id + secret) and uses the *same* pair on both servers — the two share
the same org, so they compose: provision on the hosted server, encrypt on the
local one.

## Fastest path: install the plugin

If your agent supports [Agent Plugins](https://agent-plugins.org) — Claude Code,
Codex, Cursor, GitHub Copilot, Kiro, VS Code, ChatGPT, Gemini CLI — one command
installs both servers *and* the skills that teach an agent to keep values out of
files and shell history:

```bash
npx plugins add seekritdev/agent-plugin
```

See [Agent plugin](/docs/guides/ai-agents/plugin). The rest of this page is the
manual wiring, which is still the right route for a client the installer does
not know about, or when you want only one of the two servers.

Some agent runtimes hold credentials of their own, and for those the tools are
only half the story — the other half is where the runtime's own API keys live:

| Runtime | Page |
| --- | --- |
| [Devin](https://docs.devin.ai) | [Devin](/docs/guides/ai-agents/devin) — one token in Devin's Secrets, resolved at the moment of use |
| [OpenClaw](https://docs.openclaw.ai) | [OpenClaw](/docs/guides/ai-agents/openclaw) — a SecretRef provider, so `openclaw.json` names keys instead of holding them |
| [Hermes Agent](https://hermes-agent.nousresearch.com) | [Hermes Agent](/docs/guides/ai-agents/hermes) — a secret source, so `~/.hermes/.env` holds only the token |
| [Paperclip](https://docs.paperclip.ing) | [Paperclip](/docs/guides/ai-agents/paperclip) — agent tools and a secrets panel |

## Why there are two

seekrit is zero-knowledge: secret values, data keys, and private keys never reach
the server. Decryption only ever happens where the credential lives. So anything
that produces plaintext — a secret value, a data key, a decryption-capable grant —
runs **on your machine**, on the local crypto server, next to your keys. The
hosted server serves only metadata and can *never* decrypt; it refuses service
tokens outright (they carry a private key). The division preserves seekrit's
defining property.

## 1. Connect the hosted metadata server

Point your MCP client at the hosted server. **No credential is needed to
connect** — `initialize` and `tools/list` are open, so an agent can read the
server's instructions and its whole tool list before it has an account.

```jsonc
{
  "mcpServers": {
    "seekrit": {
      "type": "http",
      "url": "https://mcp.seekrit.dev/mcp"
    }
  }
}
```

Anonymously you get the guidance tools (`get_started`, `setup_local_crypto`,
`local_tool_for`) and `signup`. Everything else returns an error telling you to
call `signup` first.

## 2. Get a machine credential (once)

Call the **`signup`** tool — no human, no browser. Name the org for the **real
project or company** you're working on: `orgName` and `orgSlug` are both required,
and a human later claims the org by that name, so a placeholder like `test` makes
it unmanageable.

```jsonc
signup { "orgName": "Acme Storefront", "orgSlug": "acme-storefront" }
// → { org: { … }, credential: { clientId: "…", clientSecret: "…" }, sessionBound: true }
```

Signup mints a fresh organization (with no human member yet) and a machine client
bound to it with admin role, then **binds that credential to the current MCP
session** — so the metadata tools work on the very next call, with no config
change and no reconnect. Save the `clientSecret`: it is shown only once, and it's
what you need to reconnect later.

With a shell in the project directory, the CLI does the same signup and keeps
going — it saves the credential where both servers read it, creates an app named
after the project with a `development` environment, and writes `seekrit.json`:

```bash
npx -y @seekrit/cli init --org-name "Acme Storefront" --yes
```

The same thing over plain HTTP, if you'd rather bootstrap outside MCP:

```bash
curl -sX POST https://mcp.seekrit.dev/signup \
  -H 'content-type: application/json' \
  -d '{"orgName": "Acme Storefront", "orgSlug": "acme-storefront"}'
# → { "org": { … }, "m2m": { "clientId": "…", "clientSecret": "…" } }
```

> **Note:** `orgSlug` is lowercase letters, numbers, and hyphens (e.g. `acme-storefront`);
>   it's disambiguated automatically if already taken. `clientName` is optional.
>   The organization starts memberless; a human joins later via invite (see
>   [Handing off to a human](#hand-off-to-a-human)).

## 3. Reconnect with the credential

A session binding lasts for that session. To come back later — or to connect a
second client — authenticate with HTTP Basic auth, your client id and secret:

```jsonc
{
  "mcpServers": {
    "seekrit": {
      "type": "http",
      "url": "https://mcp.seekrit.dev/mcp",
      "headers": { "Authorization": "Basic <base64(clientId:clientSecret)>" }
    }
  }
}
```

The hosted server runs the OAuth 2.0 client-credentials exchange for you, so the
agent never manages token refresh. It gets the metadata tools: `whoami`, the
`list_*` discovery tools, `create_app` / `create_group` / `compose_group`,
`invite_member`, `audit`, `billing`, and keyless management (`revoke_token`,
`delete_secret`, `revoke_lease`, …) — including `list_secret_versions` and
`restore_secret`, so an agent can undo a bad write without ever holding a key
(a restore replays stored ciphertext; nothing is decrypted). It can't read or
set a secret value — for that it points you at the local server:

- `get_started` — the recommended first-project recipe, end to end.
- `setup_local_crypto` — how to add the local `@seekrit/mcp` server (with a
  copy-paste `.mcp.json`) so you can set and use secret values.
- `local_tool_for` — given a crypto operation, the exact local tool that does it.

## 4. Add the local crypto server (same credential)

Register the local server with your agent and give it the **same** machine
credential. On first use it mints a long-lived admin token from those credentials
automatically and caches it — minting is keyless (the keypair is generated
locally and only its public half is registered), so the machine credential is
enough. There's no token to copy between servers. `npx` fetches `@seekrit/mcp` on
first run, so no prior install is needed:

```jsonc
{
  "mcpServers": {
    "seekrit-local": {
      "command": "npx",
      "args": ["-y", "@seekrit/mcp"],
      "env": {
        "SEEKRIT_CLIENT_ID": "<your client id>",
        "SEEKRIT_CLIENT_SECRET": "<your client secret>"
      }
    }
  }
}
```

Already have the CLI installed? Use `seekrit mcp` as the command instead of
`npx -y @seekrit/mcp` — it's the identical server. Your credentials and keys stay
on this machine; they are never sent to the hosted server.

### As a container

For an agent sandbox with no Node toolchain, the server also ships as a
multi-arch Docker image — [`seekritdev/mcp`](https://hub.docker.com/r/seekritdev/mcp),
mirrored to `ghcr.io/seekritdev/mcp` (same bytes and tags; prefer `ghcr.io` from
CI, which has no anonymous pull rate limit).
Register a stdio server that shells out to `docker run -i` — the `-i` is
required, since stdin is the MCP transport:

```json
{
  "mcpServers": {
    "seekrit": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SEEKRIT_TOKEN",
        "-v", "${PWD}:/work",
        "seekritdev/mcp"
      ]
    }
  }
}
```

The bare `-e SEEKRIT_TOKEN` forwards the token from the client's own environment,
so it never lands in the config file. Mount a workdir at `/work` if you want
`run_command` to operate on your files (it runs *inside* the container). Pin a
release (`seekritdev/mcp:0.2.0`) or track `:edge`. The container still decrypts
locally — the credential and every plaintext stay inside it, never on a remote.

## Choosing the credential

The local server authenticates exactly like the CLI. Pick per what the agent
needs to do:

| Credential | Good for | Notes |
| --- | --- | --- |
| **Machine credentials** (`SEEKRIT_CLIENT_ID` + `SEEKRIT_CLIENT_SECRET`) | Fully autonomous agents — one credential for both servers | Auto-mints and caches an admin token on first use. Get them from signup. |
| **Admin token** (`--admin`) | A fixed headless credential for provisioning | Org-scoped; create apps/groups/envs, compose, grant, mint tokens. |
| **Runtime token** (bound to an env) | Reading/writing/injecting one environment's secrets | Self-decrypts — no passphrase. Cannot provision. |

Prefer a fixed admin token instead of machine credentials? Mint one and set
`SEEKRIT_TOKEN=skt_…`:

```bash
seekrit token create --name agent-session --admin
```

## Tools

The **local crypto server** exposes the full toolset below (the hosted server has
the keyless subset listed above). Tool names are the same on both.

> **Note:** Tool names may be prefixed by your client (e.g. `seekrit:create_app`).

- **Start** — `signup` (hosted) — a workspace and your own machine credential in
  one call, bound to the session; and `get_started` — the recommended
  first-project recipe, end to end.
- **Discover** — `whoami`, `list_orgs`, `list_apps`, `list_envs`, `list_groups`,
  `list_group_envs`, `list_env_groups`, `list_members`, `list_secrets`,
  `list_secret_versions`, `list_tokens`, `audit`.
- **Provision** — `create_org`, `create_app`, `create_group`, `create_env`,
  `create_group_env`, `compose_group`, `uncompose_group`.
- **Secrets** — `set_secret`, `get_secret`, `restore_secret`, `delete_secret`.
- **Tokens & access** — `create_token`, `revoke_token`, `grant_env`.
- **Use & wire up** — `run_command`, `export_env`, `configure_project`.

Every tool carries MCP annotations, so a client that honors them can let the
read-only ones (`list_*`, `whoami`, `audit`) run unattended while still prompting
before anything that removes or overwrites — `delete_secret`, `revoke_token`,
`export_env` (it writes a file), and `run_command` (it runs a command). The
annotations describe *modification*, not sensitivity: `get_secret reveal:true`
changes nothing and is marked read-only even though it returns plaintext, so keep
using the guidance above to decide when revealing is warranted.

## Use secrets without exposing them

Prefer **`run_command`**: it resolves the environment, injects the secrets into a
child process, and returns only the command's exit code and output — the secret
values never enter the agent's context.

`get_secret` returns metadata by default; it only decrypts the plaintext into the
response when you pass `reveal: true`. Reach for that only when the value itself
is the thing you need. Pass `version` to look at an earlier one.

Wrote a bad value? `list_secret_versions` shows the history and
`restore_secret` rolls it back — as a new version, so the rollback is itself
undoable. Both work on the hosted server too: replaying stored ciphertext needs
no key.

A `set_secret` value may contain `${OTHER_SECRET}`
[references](/docs/guides/references); they are stored literally and expanded
whenever the secret is read (including by `run_command` and `export_env`), so an
agent can wire a connection string together without ever reading its parts.

> **Warning:** Revealing a secret puts its plaintext in the agent's conversation, where it may
>   be logged or retained. Use `run_command` (or `export_env` to a gitignored file)
>   whenever the agent needs to *use* a secret rather than *read* it.

## A typical session

An agent, standing up a new service from scratch:

1. Connect to the hosted server with no credential, then call `signup` → machine
   credentials + a fresh org, already active for this session. Configure the local
   server with the same credentials.
2. On the hosted server: `create_app`, then (locally) `create_env` (production) —
   the data key is generated locally.
3. `set_secret` for `DATABASE_URL`, `API_KEY`, … (encrypted on this machine).
4. `create_token` bound to that env — a runtime token, auto-granted its keys.
5. `configure_project` to write `seekrit.json`, then hand the runtime token to CI
   or a container to run `seekrit run` / `seekrit-run`.
6. `run_command -- pnpm test` to verify the app boots with its secrets injected.

## Hand off to a human

The org an agent creates has no human member. So a person can take over — and so
nothing is lost if the agent disappears — do the handoff **before the agent stops
running**:

- `invite_member <email> role:owner` (hosted) — they sign in and own the org.
- `grant_env --user <email>` (local) — re-wrap each environment's data key to
  their key so they can actually decrypt. Only a current key-holder can grant.
- Optionally configure **recovery** (M-of-N custodians) locally, so access
  survives even if the agent's admin token is gone.

## Limits worth knowing

- **Capability doesn't escalate.** A runtime (member) token is denied every
  admin route; granting a token or user decryption requires the caller to already
  hold that environment's key, so access only propagates from an existing holder.
- **Signup is rate-limited.** It's the one unauthenticated entry point, so it's
  throttled per source and globally — a real agent's single signup is never
  affected.
