# Agent plugin

The [AI agents guide](/docs/guides/ai-agents) wires seekrit up one MCP client at
a time. This page is the shortcut: seekrit ships as an
[Agent Plugin](https://agent-plugins.org), the vendor-neutral package format for
bundling **skills** (instructions an agent reads) with **MCP servers** (tools it
calls).

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

The installer detects which agents you have and translates the plugin into each
one's native format — Claude Code, Codex, Cursor, GitHub Copilot, Kiro, VS Code,
ChatGPT, Gemini CLI, and others. No `.mcp.json` editing, and nothing to repeat
per client.

## Why the skills matter more than the servers

Connecting the MCP servers gives an agent the *ability* to handle secrets
properly. It does not give it the *habit*. Left to its own devices an agent
writes the key into `.env` because that is what every tutorial it ever read
did — and when you deny it `.env`, it has been observed reading
`docker compose config`, `git log -p`, or a CI log to reconstruct the same value.

The plugin ships two skills that close that gap:

| Skill | What it teaches |
| --- | --- |
| **`seekrit-secrets`** | A value must not come to rest anywhere it can be read again. Run the process with secrets injected (`run_command`, [`seekrit run`](/docs/guides/cli)) instead of writing a file; the [resource model](/docs/guides/environments); how to bootstrap from nothing; how to model a tenant |
| **`seekrit-agent-keys`** | Give untrusted or model-generated code a credential it cannot read, with the [egress proxy](/docs/guides/agent-proxy) and `{{seekrit:NAME}}` placeholders behind a default-deny allowlist |

Skills are loaded progressively: the agent sees only each skill's name and
description until a task looks relevant, then reads the whole file. So the cost
of having them installed is a couple of lines of context, and the benefit lands
exactly when a credential is about to be mishandled.

## What gets installed

```
seekrit/
├── plugin.json
├── mcp.json                 →  both servers, below
└── skills/
    ├── seekrit-secrets/     →  SKILL.md + references/{model,cli}.md
    └── seekrit-agent-keys/  →  SKILL.md + references/proxy-config.md
```

Two MCP servers, split along seekrit's encryption boundary:

- **`seekrit`** — local, over stdio (`npx -y @seekrit/mcp`). Everything that
  touches a secret *value*: `set_secret`, `get_secret`, `run_command`,
  `create_env`, `create_token`, `grant_env`, KMS, database leases. Decryption
  happens here because this is where your key is.
- **`seekrit-cloud`** — hosted, `mcp.seekrit.dev`. Metadata and management with
  no install: orgs, apps, environments, groups, composition, members, audit,
  billing, secret *names*. It holds no key and cannot decrypt anything.

One machine credential drives both. The local entry is deliberately unpinned so
an install never goes stale against the published package.

## Signing in

Connecting needs no account. Ask the agent to call `signup` on the hosted
server — it mints an organization and a machine credential in-band, with no
browser and no card — then persist it so both servers keep working:

```bash
seekrit login --client-id <id> --client-secret <secret>
```

That writes `~/.config/seekrit/config.json`, which the local server reads with
no environment plumbing. If you already have a service token,
`seekrit login --token skt_…` does the same job. Machine credentials
[auto-mint an admin token](/docs/guides/service-tokens), which is what lets one
credential serve both planes.

## Verifying it took

Ask the agent to run `whoami`, then `list_apps`. If the local server reports no
credential, the config file is missing or the client did not pass its
environment through — `seekrit login` fixes both. `local_tool_for` on the hosted
server names the local tool for any task the hosted plane cannot finish.

## Auditing what your agent was told

The plugin is mirrored to [seekritdev/agent-plugin](https://github.com/seekritdev/agent-plugin)
from seekrit's monorepo, so the exact instructions your agent follows are
readable in public — the same reason the [SDKs](/docs/guides/sdks) are mirrored.
Issues and PRs are welcome there; changes land in the monorepo and overwrite the
mirror on the next sync.