# AI agents

seekrit speaks [MCP](https://modelcontextprotocol.io) through `seekrit mcp`, a
stdio server bundled in the CLI. Point an agent (Claude Code, or any MCP client)
at it and the agent can create orgs, apps, groups, and environments, manage
secrets, mint and grant service tokens, and run commands with secrets injected —
all as tools.

## Why the server is local

seekrit is zero-knowledge: secret values, data keys, and private keys never
reach the server. Decryption only ever happens where the credential lives. So
the MCP server runs **on your machine**, next to that credential — a hosted
`mcp.seekrit.dev` could only serve metadata, never decrypt. Everything that
produces plaintext (a secret value, a data key, a decryption-capable grant)
stays on the client. That is the whole point of seekrit, preserved.

## Setup

Register the server with your agent, passing a credential in its environment:

```bash
# Claude Code — an admin token lets the agent provision structure too:
SEEKRIT_TOKEN=skt_… SEEKRIT_API_URL=https://api.your-seekrit.example \
  claude mcp add seekrit -- seekrit mcp
```

Any MCP client works — configure a stdio server whose command is `seekrit mcp`
with `SEEKRIT_TOKEN` (and `SEEKRIT_API_URL`) in its environment.

## Choosing the credential

The server authenticates exactly like the CLI — `SEEKRIT_TOKEN`,
`SEEKRIT_DEV_USER`, or saved config. Pick per what the agent needs to do:

| Credential | Good for | Notes |
| --- | --- | --- |
| **Admin token** (`--admin`) | Provisioning: create apps/groups/envs, compose, grant, mint tokens | Org-scoped; the only headless way to create structure. |
| **Runtime token** (bound to an env) | Reading/writing/injecting one environment's secrets | Self-decrypts — no passphrase. Cannot provision. |
| **User + `SEEKRIT_PASSPHRASE`** | A human handing their own access to a local agent | Needed to create an *org* (tokens can't own a Stytch org). Set the passphrase in the server env — stdin is the transport, so there is no prompt. |

Mint an admin token for an agent session, then let the agent mint scoped runtime
tokens for the workloads it sets up:

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

## Tools

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

- **Discover** — `whoami`, `list_orgs`, `list_apps`, `list_envs`, `list_groups`,
  `list_group_envs`, `list_env_groups`, `list_members`, `list_secrets`,
  `list_tokens`, `audit`.
- **Provision** — `create_org`, `create_app`, `create_group`, `create_env`,
  `create_group_env`, `compose_group`, `uncompose_group`.
- **Secrets** — `set_secret`, `get_secret`, `delete_secret`.
- **Tokens & access** — `create_token`, `revoke_token`, `grant_env`.
- **Use & wire up** — `run_command`, `export_env`, `configure_project`.

## 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.

> **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, holding an admin token, standing up a new service:

1. `create_app` → `create_env` (production) — the data key is generated locally.
2. `set_secret` for `DATABASE_URL`, `API_KEY`, … (encrypted on this machine).
3. `create_token` bound to that env — a runtime token, auto-granted its keys.
4. `configure_project` to write `seekrit.json`, then hand the runtime token to CI
   or a container to run `seekrit run` / `seekrit-run`.
5. `run_command -- pnpm test` to verify the app boots with its secrets injected.

## Limits worth knowing

- **Creating an organization needs a user session.** A Stytch org must have a
  human owner, so `create_org` works under user auth (or local `AUTH_MODE=dev`),
  not under a token. Everything *inside* an org is available to an admin token.
- **Capability doesn't escalate.** A runtime (member) token is denied every
  admin route; granting a token decryption requires the caller to already hold
  that environment's key, so access only propagates from an existing holder.