MCP server

Connect an agent to enveil over the Model Context Protocol

The enveil server exposes its store over MCP (Streamable HTTP) at /mcp, for example https://enveil.oxidt.com/mcp. An agent can list projects, environments and keys, write and roll back secrets, and, when its credential allows, read values.

Connecting

There are two ways to authenticate, and they decide who the agent acts as.

A machine identity. Send its evl_… token as Authorization: Bearer evl_… or X-API-Key: evl_…. The agent acts as that identity and is bounded by its scopes, expiry and read budget. This is the one to give an agent that works unattended.

sh
claude mcp add --transport http enveil https://enveil.oxidt.com/mcp \
  --header "Authorization: Bearer $ENVEIL_TOKEN"

Add --scope user to make it available in every project, or --scope project to write it to .mcp.json. Do not commit a token there.

OAuth, as yourself. A request with no credential gets 401 with a WWW-Authenticate header pointing at https://enveil.oxidt.com/.well-known/oauth-protected-resource. Clients such as Claude Code follow it, register themselves, and send you through the browser to approve. The token they get is granted the mcp scope and acts as you, with your role in the organization and every project you can reach. Its reads are metered against the default budget.

sh
claude mcp add --transport http enveil https://enveil.oxidt.com/mcp

Then run /mcp inside Claude Code and follow the browser sign-in. If you pass an Authorization header, Claude Code does not fall back to OAuth when the header is refused.

Requests are also limited per IP address to 120 a minute, answered with HTTP 429.

Tools

Projects and environments are addressed by slug, as in the CLI. Every tool has openWorldHint: false.

Tool What it does Discloses a value Recorded Annotations
whoami Who the credential is, its organization; for a machine identity its scopes and expiry No No readOnlyHint: true
list_projects Projects the credential can see, with slugs No No readOnlyHint: true
list_environments Environments of a project No No readOnlyHint: true
list_secrets Keys, which environments hold a value or a link (with its source, project/environment:KEY), and allowed proxy hosts No No readOnlyHint: true
get_secret One value Yes secret_read, charged 1 against the budget readOnlyHint: false
export_environment Every value in one environment as .env text Yes, all of them One environment_exported, charged one unit per secret readOnlyHint: false
set_secret Create or replace a value in one environment; optionally set proxy_hosts No, the value is not echoed secret_created or secret_updated; secret_proxy_hosts_changed readOnlyHint: false, destructiveHint: false, idempotentHint: false
secret_history Versions of a key: number, time, who changed it No No readOnlyHint: true
rollback_secret Restore an earlier version as current, without returning it No secret_updated readOnlyHint: false, destructiveHint: false, idempotentHint: true
link_secret Make a key in one environment a link to a value in another project; source environment and key default to the linking ones; replace: true archives the key's own value there and links in one step No secret_linked readOnlyHint: false, destructiveHint: false, idempotentHint: true
trust_policy_list OIDC trust policies: issuer, subject, audience, project, environment, access, and whether the subject is now refused No No readOnlyHint: true
trust_policy_create Register a trust policy for one project, optionally one environment; access defaults to read No trust_policy_created readOnlyHint: false, destructiveHint: false, idempotentHint: false

get_secret and export_environment deliberately do not claim to be read-only: clients decide what to auto-approve from these hints, and a call that hands out a credential should not be approved like a listing.

Scopes apply per call. get_secret, export_environment and secret_history need read on the environment; set_secret and rollback_secret need write. Setting proxy_hosts needs write on the whole project, since hosts apply in every environment; it is checked before the value is written, so a refusal leaves nothing half-applied. A proxy-only identity can list, but every value-returning tool refuses it.

get_secret and export_environment resolve a linked key to the source's current value, and record the read against the environment that was read, with the source named. set_secret, secret_history and rollback_secret refuse a linked key: its value and history live at the source. link_secret needs write on the linking environment and read on the source, and like the trust policy tools a person's credential of an admin or owner. There is no unlink tool; remove a link with enveil delete or the dashboard.

The trust policy tools refuse a machine identity: a policy is managed by a person, as in the dashboard. Creating one needs an admin or owner and runs the dashboard's own checks: an https issuer, a subject wildcard that names an owner, and a project and environment in the credential's organization.

Errors

Three refusals come back as a tool result with isError: true rather than a protocol error, so the client shows them to the model. The same fields are in structuredContent and in the text content:

json
{
  "error": "This credential has read 61 secrets in the last minute, over its limit of 60. …",
  "reason": "read_budget_exceeded",
  "retryable": true
}
reason Meaning What the client should do
read_budget_exceeded The credential went over its reads per minute or hour Wait for the window to reset. Do not retry in a loop; tell the person
rate_limit_exceeded Another rate limit tripped The same: wait for the window, do not loop
conflict The write clashes with what is already stored Change the input; retrying the same call fails again

retryable: true means the same call can succeed later, not that it should be retried now. Each refused read is still counted and recorded as identity_throttled.

Everything else is a JSON-RPC error: a missing or invalid credential, a credential without the mcp scope, a missing scope (the message names the capability and project/environment, so an admin knows which scope to grant), invalid parameters, or a key that does not exist.

Unscoped projects look absent

A machine identity sees only projects it holds a scope on. list_projects leaves the others out, and naming one in any tool returns the same "No project with slug …" as a project that does not exist. An agent cannot map the organization by guessing slugs. When an expected project is missing, check whoami before assuming it was deleted.