AI agents

seekrit speaks MCP 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). 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 — 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:

npx plugins add seekritdev/agent-plugin

See Agent 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.

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). That division is the whole point of seekrit, preserved.

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.

{
  "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.

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.

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

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

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:

{
  "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:

{
  "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. Register a stdio server that shells out to docker run -i — the -i is required, since stdin is the MCP transport:

{
  "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:

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

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.

• 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; 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.

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.