VaulticMCP Server
Give agentic tools like Claude the ability to interface with the Vaultic API.
The Vaultic MCP Server implements the Model Context Protocol, allowing agentic AI tools to interface with the Vaultic API — list workspaces, projects, and environments; read, set, and reveal secrets; diff and promote between environments; and manage service tokens.
The Vaultic MCP Server is experimental and intended for development, testing, and evaluation purposes. Because outputs are non-deterministic and vary with the connected model, query, and session state, always scope the connection to only the workspace, project/environment, and read-vs-write access you intend to allow, and review agentic output for alignment with your security and compliance requirements.
Prerequisites
- An MCP client that supports remote/HTTP connectors (Claude Desktop, claude.ai, and others)
- A Vaultic account you can log into in your browser
No local install, no JSON config file, and no credential to copy/paste — connecting happens entirely through your MCP client's UI and a browser-based approval screen.
Setup
Add the connector
In your MCP client, go to Settings → Connectors → Add custom connector and paste the gateway
URL: https://mcp.vaultic.dev on the hosted service, or your own gateway's URL if you're
self-hosting (see Self-hosting the gateway below).
Approve in your browser
Your client opens a browser tab and sends you to Vaultic to log in (if you aren't already) and shows a consent screen: pick which workspace, and optionally which project/environment, the client should be scoped to, and whether it gets read or write access.
Approving creates (or reuses) an agent identity for you and this client, and starts a scoped session under it — every action it takes is attributed to both of you in the audit log (see Scoping access below). The client never sees or handles the underlying credential directly, and you're returned to it, connected.
Try it
Ask your client something like "list my Vaultic workspaces" or "what secrets are set in
the production environment of the backend-api project?" — it should call
vaultic_list_workspaces / vaultic_list_secrets and show you the (masked) result.
Still early: connection state lives in the gateway process's memory, so it doesn't survive a
restart, and there are no OAuth refresh tokens yet — your client has to redo browser approval
about once a month, when the underlying session expires (~30 days). Disconnecting a client from
Settings → Connectors only stops the gateway from accepting that session going forward —
revoking access for real still requires ending the session from the workspace's Agents page
(or vaultic agent session end).
Self-hosting the gateway
The gateway (packages/mcp-gateway) is a separate service from server/web — it's off by
default in docker-compose.prod.yml and needs its own public HTTPS origin:
| Env var | Required | Purpose |
|---|---|---|
MCP_GATEWAY_ISSUER_URL | yes, to enable it | This gateway's own public https:// URL, e.g. https://mcp.your-vaultic-instance.com. Also read by web (as VITE_MCP_GATEWAY_URL) so the consent screen knows which gateway origin to trust |
WEB_APP_URL | yes | Your web app's origin, so the gateway knows where to send users for consent |
Leave MCP_GATEWAY_ISSUER_URL unset to skip deploying the gateway entirely — the consent page
just refuses every request rather than trusting an unvalidated origin, so nothing breaks on the
rest of the deployment.
Tools
| Tool | Description |
|---|---|
vaultic_list_workspaces | List workspaces visible to the token |
vaultic_list_projects | List projects in a workspace |
vaultic_create_project | Create a project, optionally seeding environments |
vaultic_list_environments | List environments in a project |
vaultic_create_environment | Create a base or inheriting/sandbox environment |
vaultic_diff_environments | Diff two environments' secret keys (no values) |
vaultic_promote_environment | Copy changed/added values from one environment to another |
vaultic_list_secrets | List secrets in an environment, masked |
vaultic_get_secret | Get one secret's metadata, masked |
vaultic_reveal_secret | Get one secret's real value (separately audited) |
vaultic_set_secret | Create or update a secret's value/metadata |
vaultic_delete_secret | Soft-delete a secret |
vaultic_get_secret_history | List a secret's version history, optionally revealed |
vaultic_list_service_tokens | List service tokens in a workspace |
vaultic_create_service_token | Create a scoped service token |
vaultic_revoke_service_token | Revoke a service token |
Each tool's full description — arguments, return shape, and error cases — is visible to the connected MCP client; that's the source of truth, not this table.
Not covered (use the CLI or web app instead): webhooks, member/invite management, access grants, secret comments, Git integration, secret sharing links, and rotation plugins — lower-frequency, higher-blast-radius operations that don't fit naturally into an agent workflow.
Scoping access
Every request the MCP server makes is tagged x-vaultic-source: mcp, so anything an agent does
shows up in the workspace's audit log with source: "mcp" —
distinct from cli, ui, and plain api activity, and attributed to both the agent identity and
the human who approved the connection (agent:name (session ...) on behalf of you@...). Reveals
(vaultic_reveal_secret, and reveal: true on vaultic_get_secret_history) are further logged
as their own audited action.
Scope is chosen on the consent screen each time you connect — pick the narrowest workspace, project/environment, and read-vs-write access the client actually needs, the same discipline you'd apply to a manually-created service token. Approving the same client again later reuses its existing agent identity rather than creating a new one, so you can review and manage every connected client from the workspace's Agents page — see who's connected, what they're scoped to, and end a session immediately if something looks wrong.