Connect an AI agent (MCP)

Most MCP servers ask you to paste an API key into a JSON config file. That key is long-lived, scoped to everything the key can do, sits in plaintext on disk, and leaves no record of what was done with it. VaultTerm takes the opposite approach: the agent gets access, not credentials.

When an AI assistant connects to VaultTerm over the Model Context Protocol, it authenticates as an agent principal — a non-human identity that belongs to you, expires on its own, and can be revoked without touching your own sessions. When it uses a credential, the secret is decrypted on the server, used, and discarded. It never crosses the wire to the model.

Connect a client

One command, from a machine where you are signed in to the CLI:

vt mcp install --client claude-code

Supported values for --client:

Client	Config written	Scope
claude-code	.mcp.json in the current directory	Project
claude-desktop	claude_desktop_config.json in your Claude application-support directory	User
cursor	~/.cursor/mcp.json	User
copilot	.vscode/mcp.json in the current directory	Workspace

Use --dir to write a project-scoped config somewhere other than the current directory.

The command mints an agent principal, stores its credential in your operating system’s keychain, writes the client config, and verifies the connection before it reports success. Then restart the client — Claude Desktop needs a full quit and reopen; Claude Code will ask you to approve the project-scoped server the first time you run it.

The config file contains no secret

This is the part that matters. The entry we write looks like this:

{
  "mcpServers": {
    "vaultterm": {
      "command": "vt",
      "args": ["mcp"],
      "env": { "VT_API_BASE": "https://your-vaultterm-host" }
    }
  }
}

There is no token in it. vt mcp reads a short-lived credential from your OS keychain at launch, so the file is safe to commit to a repository, safe to screenshot, and safe to share with a teammate who will run vt mcp install themselves. Revoking access never requires editing it.

What the agent can do

The agent sees only the tools its scopes allow, and can only reach what you can reach — an agent is a delegation of your access, never an escalation of it. By default it is granted:

Scope	Tools	What it can do
vault.list	vault_list, vault_search	See which vaults and credentials exist. Metadata only — never a value.
vault.use	vault_use	Authenticate to an existing connection with the credential bound to it and report whether it worked. The tool takes a connection id, not a host, and returns no secret material.
ssh.exec	ssh_run	Run a command on a brokered host and get its output and exit code.
files.read	files_list, files_get	Browse and read files over SFTP, FTP/FTPS, WebDAV or object storage.
audit.read	audit_query	Read its own audit trail — not yours, and not another agent’s.

Two discovery tools sit alongside these and are granted by any scope that needs them: ssh_list returns the SSH connections the agent can reach, and files_connections returns the FTP/FTPS/WebDAV and object-storage targets. Both are metadata only. They are how the model learns the connection ids that ssh_run, vault_use and the file tools take — a connection whose credential sits in a vault the agent cannot read is left out rather than advertised and then refused.

Two more scopes are available but off by default, and minting a principal with either requires a fresh step-up so that granting them is a deliberate act by a present human:

• vault.reveal — the only tool that returns plaintext secret material. vault_reveal refuses a credential marked inject-only, for every agent, regardless of scope. Note that the flag constrains the reveal path rather than containing the secret: it is not a barrier against a person who can point a connection at a host they control — see SSH broker overview.
• files.write — modifying remote files.

Choose scopes explicitly with --scopes:

vt mcp install --client cursor --scopes vault.list,ssh.exec --days 7

Narrowing further

An agent principal can be restricted to specific vaults or connections, so a coding assistant wired to one project cannot reach the rest of your infrastructure. Set this when minting from the web console; the restriction only ever narrows what you can reach, never widens it.

Where the agent’s model runs

When you connect an agent you declare whether its model is hosted (Claude, Copilot, Cursor’s cloud models — your context leaves your network) or self-hosted on your network.

We ask rather than detect, deliberately. The only signal a connection carries is the client’s own self-reported name, which anything can set to anything; enforcing a security policy on that would look like protection without being it. A declaration is made by a person, recorded, and auditable.

By default any class is allowed — you chose the client, and it is already receiving your context. An organization that needs the restriction can turn on require agents to run on our own network, after which only self-hosted agents can be connected or used. Because an undeclared agent is treated as hosted, turning the policy on refuses anything that has not been explicitly vouched for rather than silently assuming it is safe. Agents already issued are suspended on their next call, not at the end of their lifetime.

vt mcp install --client claude-code --egress lan

What is protected

• Output is redacted. Command output and file contents pass through the same redaction gate as every other AI feature before they reach the model.
• Fetched content cannot pose as instructions. A file or a command’s output can contain text aimed at the model reading it — “ignore your previous instructions”, a forged role marker. Tool results are returned as fenced, marked-up-as-data spans with those markers stripped, so something the agent read cannot impersonate something you said.
• Your file policy still applies. A brokered read by an agent is evaluated against the same data-loss policy as any other file access, and refused if the policy refuses it.
• Arguments are screened. A model that has read a web page, a log line or a ticket can be steered into calling a tool with hostile arguments. Tool arguments cross the prompt-injection guard before any brokered action runs, and attempts to exfiltrate secrets are refused and recorded.
• Arguments are validated, and tools say what they do. Every tool publishes a JSON Schema for its arguments and for its results, and the server validates arguments against it before anything runs — a malformed call comes back as something the model can correct rather than as a half-done action. Each tool also carries the protocol’s behaviour hints, so a client can tell you that ssh_run changes things on a host before it runs, and can decline to treat vault_reveal as safe to approve on your behalf.
• Tool calls are rate limited. Every agent principal has a floor on how many tool calls it can make per minute, so a model stuck in a retry loop cannot hammer a brokered host. Exceeding it answers 429 with a Retry-After; vt mcp status and GET /mcp/whoami report the limit in force.
• Everything is audited. Every tool call is attributed to the agent principal, its owner, and the client it was minted for. You can answer “what did the AI do in our environment” with evidence.
• On-LAN by default. If your organization runs a self-hosted model, terminal output never leaves your network — see AI privacy model.

Approve a reveal as it happens

An organization can require a human to approve each secret reveal at the moment the agent asks for it, rather than deciding once when the agent is minted. With MCP_JIT_APPROVAL turned on, a vault_reveal call comes back as a question rather than a secret: your MCP client shows an approval prompt naming the credential, and the reveal completes only after you accept.

Each approval covers exactly one call. It is bound to that agent, that credential and that request, expires in minutes, and is redeemed server-side so a captured approval cannot be replayed into a second reveal. A client that cannot show an approval prompt is refused rather than allowed through, so the control cannot be sidestepped by connecting a simpler client.

This is off by default, and today it applies to vault_reveal only.

Check and revoke

vt mcp status

Shows the stored credential, when it expires, which scopes it holds, and which clients on this machine are wired up.

vt mcp uninstall --client claude-code

Revokes the agent principal, removes our entry from the client config — leaving any other MCP servers you have configured untouched — and clears the stored credential. Revocation takes effect on the agent’s next call, not when its TTL expires.

Each client holds its own credential, so uninstalling one leaves the others working. Omit --client to remove every client at once. Re-running install for a client you already set up replaces it: the new principal is minted and the old one revoked, rather than both staying live.

You can also revoke from the web console at any time, including agents belonging to other members of your organization if you are an org admin. An expired or revoked principal stops authenticating immediately; so does one whose owner is deactivated or moved out of the organization.

Plan limits

Agent access is available on every plan, with a limit on how many agents can be live at once. The count is of live principals, so revoking one or letting it expire frees the slot immediately. See Billing and plans.

Protocol notes

VaultTerm implements MCP revision 2026-07-28 and also answers the older handshake-based revisions, so clients that have not yet updated keep working. The server is reachable two ways:

• stdio — vt mcp, which is what vt mcp install configures. The CLI bridges your local client to the server; the broker itself always runs server-side.
• Streamable HTTP — POST /mcp on your VaultTerm host, for a client that can hold a bearer credential directly.

Both authenticate with an agent principal. A normal user session token is refused on both.

Authorization discovery

POST /mcp publishes OAuth 2.0 Protected Resource Metadata (RFC 9728) at /.well-known/oauth-protected-resource and /.well-known/oauth-protected-resource/mcp, so a standards-compliant MCP client can discover what this resource is and which scopes an operation needs instead of being wired to a credential by hand. Unauthenticated calls answer 401 with a WWW-Authenticate challenge carrying resource_metadata and a baseline scope; a call the agent’s scopes do not cover answers 403 with error="insufficient_scope" and every scope that would satisfy it, in one challenge.

VaultTerm names itself as the authorization server in that document — it mints the credential and owns the consent surface. The OAuth 2.1 endpoints behind that name (authorize, token, client registration) are not built yet: today the agent-principal bearer that vt mcp install provisions is the credential that works, and discovery is additive on top of it.