seekrit — secrets for agents

Create a seekrit workspace and your own machine credential — one call, no human, no browser. Binds the credential to this session, so every other tool works on your next call with no config change and no reconnect. Returns { org, credential: { clientId, clientSecret }, sessionBound, next }. Save the clientId + clientSecret: the secret is shown once, is not retrievable, and is how you reconnect later. Call this if a tool says you have no credential.

Read the recommended first-project recipe end to end: which steps run here and which need the local crypto plane. Takes no arguments and returns a prose walkthrough. Call this before provisioning anything — it is cheaper than discovering the plane boundary one failed tool at a time.

Takes no parameters.

Get the exact commands for running the local crypto plane (the `@seekrit/mcp` npm server, the `@seekrit/cli` CLI, seekrit-run, seekrit-proxy), including a copy-paste .mcp.json that reuses this session's credential. Takes no arguments and returns prose plus config. Call this the moment you need to SET or READ a secret value — no tool on this server will ever return one. Use local_tool_for instead when you want the single command for one named operation.

Takes no parameters.

Look up how to perform one crypto-plane operation locally — the targeted answer for "the tool I expected is not on this server". Returns { operation, where, how } for a known operation, or a note explaining the plane boundary for an unrecognised one. Use setup_local_crypto instead when you need the whole local setup rather than one command.

Show the authenticated machine client and the org it can access. Call this first: it confirms the credential works and tells you which org slug to pass (or that you can omit `org` entirely). Returns { kind, clientId, orgs: [{ id, name, slug, role, createdAt }] }.

Takes no parameters.

List the organizations this credential can access. Use it to find the `org` slug every other tool takes; prefer whoami if you also want to confirm which client you are. Returns [{ id, name, slug, role, createdAt }].

Takes no parameters.

List the applications in an organization — an application is the top-level container that owns environments, which in turn own secrets. Start here when you know the org but not the app slug the other tools need. Returns [{ id, orgId, name, slug, createdAt }]; use list_envs next to descend into one.

List the environments an application owns (production, staging, …). Names and slugs only — never values. Use this to find the `env` slug that list_secrets and the delete/restore tools take. Returns [{ id, name, slug, applicationId, groupId, parentEnvironmentId, expiresAt, createdAt }]. Not to be confused with list_env_groups (which groups feed INTO an app environment) or list_group_envs (the environments of a shared GROUP).

List ephemeral branch configs (per-PR / preview environments) across an application, or just those forked from one environment. Names, parents, and expiry only — never values. Use it before delete_branch to find a branch slug, or to spot branches that have already expired. Returns Environment rows with `parentEnvironmentId` set: [{ id, name, slug, parentEnvironmentId, expiresAt, createdAt }] — `expiresAt` is null for a branch with no TTL.

List the shared groups in an organization — a group is a reusable bag of secrets (a shared datastore, a vendor account) that many application environments can compose in rather than duplicating. Use it to find the `group` slug compose_group and list_group_envs take. Returns [{ id, orgId, name, slug, createdAt }]; not paginated.

List the environments belonging to one shared GROUP — a group holds a separate value set per slug, so its `production` differs from its `staging`. Use this when you already have a group and want its own environments; use list_envs for an application's, and list_env_groups to see which groups an application environment pulls from. Returns Environment rows with `groupId` set: [{ id, name, slug, groupId, createdAt }].

List the shared groups composed INTO one application environment, in precedence order (higher position wins a name clash). Read this to explain where a secret name actually comes from, or to pick the next `position` for compose_group. The inverse direction of list_group_envs. Returns [{ groupId, slug, name, position }], highest position last.

List organization members with their public keys. The public keys are what you pass to `grant_env` on the LOCAL crypto plane to give a human the ability to decrypt — so call this when handing a project off to a person. Returns [{ userId, email, name, role, publicKeyJwk }]; `publicKeyJwk` is null for a member who has not finished key setup, and such a member cannot be granted decryption yet.

List the secret NAMES and versions in an environment. NEVER returns values: this server cannot decrypt. Use it to discover which names exist before referencing them; to read a value, run the local crypto plane (see setup_local_crypto) — no tool here will ever return one. Returns [{ name, version, updatedAt }].

List one secret's version history: who wrote each version, when, and which ones were restores. Metadata only — never values. Pair with restore_secret to undo a bad write: read the history here, then pass the version number you want back. Returns { currentVersion, versions: [{ version, createdAt, createdBy, restoredFromVersion }] }, newest first.

List an organization's service tokens — the long-lived credentials that let a deployed workload fetch secrets. Metadata only: the token strings are shown once at creation (on the local crypto plane) and are never retrievable here. Use it to find a `tokenId` for revoke_token, or to audit what still has access. Returns [{ id, name, role, environmentId, expiresAt, lastUsedAt, revokedAt, createdAt }] — `environmentId` is null for an org-admin token, and a non-null `revokedAt` means it is already revoked.

List invitations to the organization that have been sent but not yet accepted. Use it to confirm an invite_member call landed, or to find an `inviteId` for revoke_invite. Accepted invitations become members — see list_members. Returns [{ id, orgId, email, role, invitedById, createdAt }].

List the managed KMS keys the caller can see — symmetric and signing keys seekrit stores wrapped, for encrypting data outside the secret store. Metadata only: key material is fetched and used on the local crypto plane (kms_encrypt / kms_decrypt / kms_sign live there, not here). Use it to find a `keyId` for kms_disable_key or kms_revoke_grant. Returns [{ id, name, purpose, spec, currentVersion, applicationId, groupId, disabledAt, createdAt }] — a non-null `disabledAt` means the key is already disabled.

List the registered temporary-access targets — the databases (Postgres, MySQL, …) against which short-lived credentials can be minted on demand instead of storing a standing password. Use it to see what can be leased before minting one (create_pg_lease / create_mysql_lease run on the LOCAL crypto plane), and see list_leases for what has actually been issued. Returns [{ id, orgId, provider, name, config, createdAt }], where `provider` names the kind of target (postgres, mysql, …) and `config` is non-secret connection settings.

List temporary-access leases that have been issued — the ledger of who got a short-lived credential against which target and until when. Never includes the credential itself. Use it to find a `leaseId` for revoke_lease, or to check whether a lease has already expired before revoking it; list_lease_targets shows what CAN be leased. Returns [{ id, targetId, provider, status, principalType, principalId, expiresAt, endedAt, endedReason, createdAt }] — only `status: "active"` leases are worth revoking.

Read the organization's append-only audit trail, most recent first — every mutation across apps, environments, secrets, members, and tokens. Use it to answer "what changed and who did it"; for one secret's history specifically, list_secret_versions is narrower and cheaper. Returns [{ id, action, actorType, actorId, resourceType, resourceId, metadata, ipAddress, createdAt }].

Show the org's plan, effective entitlements, current usage, and which upgrade actions are available. Read this if a create action was refused with a plan limit — it names the limit you hit and how to lift it. Returns { plan, subscription, promo, entitlements, usage, overrides, enforced, manage } — `enforced: false` means plan limits are not currently applied, and `manage` carries the upgrade paths.

Create an application — the container that will own environments and secrets. This step needs no key material, so it runs here. Creating its environments does NOT: create_env mints a data key and lives on the local crypto plane (call setup_local_crypto). Returns the new { id, orgId, name, slug, createdAt }.

Create a shared group — a reusable bag of secrets (a shared datastore, a vendor account) that many application environments compose in rather than each keeping a copy. Use create_app instead for a deployable service. No key material involved, so it runs here; the group's environments are minted locally by create_group_env. Returns the new { id, orgId, name, slug, createdAt }.

Compose a shared group into an application environment, so that environment resolves the group's secrets as well as its own. Safe to repeat — composing an already-composed group just updates its position. Use uncompose_group to undo, and list_env_groups to see the current order. No key material involved, so it runs here. Returns the composed { groupId, slug, name, position }.

Remove a composed group from an application environment. The group and its secrets are untouched — only the link is dropped — but the environment stops resolving every name it inherited from that group, which will break a workload still reading one. Check list_env_groups first, and use delete_group to destroy the group itself. Safe to repeat. Returns { ok: true }.

Invite a human to the organization by email (admin only). They join at the given role once they sign in. Use this to hand a project off to a person — then grant them decryption with `grant_env` on the LOCAL crypto plane, since an invite alone conveys no ability to read values. Returns the pending { id, orgId, email, role, invitedById, createdAt }; revoke_invite cancels it.

Change an application's display name. The slug is immutable — every other tool refers to the app by slug, so a rename breaks nothing. Use delete_app + create_app only if the slug itself must change. Returns the updated { id, orgId, name, slug, createdAt }.

Change a shared group's display name. The slug is immutable — references from composed environments are by slug, so a rename breaks nothing. Returns the updated { id, orgId, name, slug, createdAt }.

Roll a secret back to an earlier version — the undo for a bad write. The stored ciphertext is replayed as a NEW version, so history is append-only and nothing is overwritten. Read list_secret_versions first to choose the version. No decryption happens, which is why this works here and not only on the local crypto plane. Returns { ok, name, restoredFrom, version } where `version` is the new head.

Delete a secret from an environment, discarding its ciphertext and every version. Irreversible — restore_secret CANNOT bring it back (that only rolls back within a surviving secret's history), and re-creating it means setting the value again on the local crypto plane. Prefer restore_secret to undo a bad write. Confirm intent before calling. Returns { ok, name } — or { ok, queued: true, changeRequestId } if the environment requires approval, in which case NOTHING was deleted until a human approves.

Revoke a service token by id. Future key fetches by that token stop immediately, so any workload still using it loses access on its next read. If the holder may have cached the key already, also rotate the environment on the local crypto plane — revocation alone does not re-encrypt anything. Find the id with list_tokens. Returns { ok, tokenId }.

Cancel a pending organization invitation before it is accepted. Use this for an invite sent in error; once someone has accepted, they are a member and this no longer applies. Find the id with list_invites. Returns { ok, inviteId }.

Revoke a temporary-access lease now instead of waiting for it to expire — the leased database credential is dropped at the target immediately, so anything still holding it fails on its next connection. Irreversible: a new lease must be minted on the local crypto plane. Check list_leases first, since an already-expired lease needs no revoking. Returns { ok, leaseId }.

Disable a managed KMS key: new encrypt/sign operations are blocked, while data already encrypted under it stays decryptable locally by existing grantees. Reversible only by an operator re-enabling the key — there is no enable tool here. Use kms_revoke_grant instead to cut off ONE principal while the key stays in service. Find the id with kms_list_keys. Returns the updated key, with `disabledAt` now set.

Revoke one principal's grant on a managed KMS key, across all its versions — that user or service token can no longer use the key, while everyone else keeps working. Use kms_disable_key instead to stop the key entirely. Removing a grant needs no key material, which is why it runs here. Returns { ok, keyId, principalId }.

Delete an application together with all of its environments and their secrets, discarding the ciphertext. Irreversible — there is no undo and no export. This is the widest-blast-radius tool here; prefer delete_env for a single environment, or rename_app if the name is the only problem. Confirm intent with a human before calling. Returns { ok, app }.

Delete a shared group together with its environments and their secrets, discarding the ciphertext. Irreversible. Every application environment that composed this group loses those names — check list_env_groups (or use uncompose_group) before deciding the group is unused. Confirm intent before calling. Returns { ok, group }.

Delete one application environment and the secrets it owns, discarding the ciphertext. Irreversible, and the environment's data key goes with it — recreating the environment means setting every value again on the local crypto plane. Sibling environments and the application itself are untouched; use delete_app to remove all of them. Confirm intent before calling. Returns { ok, env }.

Tear down an ephemeral branch config and every value it overrode. The parent environment is untouched — only the branch's own overrides go — which makes this the routine cleanup when a PR merges. Irreversible; creating a branch mints a data key, so create_branch stays on the local crypto plane. Find the slug with list_branches. Returns { ok, branch }.