MCP Server (AI Agents)

Connect AI coding assistants like Claude Code and Cursor to varsafe via the Model Context Protocol. Your AI agent can list projects, read secrets, set values, compare environments, and export configurations — all with fine-grained permissions and a full audit trail.

Two Ways to Connect

varsafe offers two equivalent MCP endpoints — pick whichever fits your workflow:

Option	Transport	Auth	Best for
Hosted	HTTPS	OAuth 2.1	Zero-config: browser-based consent, no tokens to manage
Local stdio	stdin/out	API token	Local inspection, self-hosting, or MCP clients without URL support

Both expose the same 9 tools with identical behaviour. The Hosted option is the default recommendation — most users should start there.

How It Works (Hosted)

Discover — Your AI tool reads the MCP server URL and discovers OAuth endpoints automatically
Consent — Your browser opens a consent screen where you choose teams, scopes, and optional restrictions
Authorize — The agent receives an OAuth 2.1 access token (PKCE-secured, 1-hour expiry, auto-refreshed)
Use — The agent calls varsafe tools with the token; every action is audited

Quick Setup

Add the varsafe MCP server to your AI tool's configuration.

Claude Code

Run the claude mcp add command:

bash

claude mcp add --scope user --transport http varsafe https://api.varsafe.dev/mcp

--scope user registers the server globally for every project (written to ~/.claude.json). Drop it to add the server to the current project's .mcp.json instead, which you can commit to share with teammates.

Prefer to manage the config by hand? Drop this into a .mcp.json at the repo root:

json

{
  "mcpServers": {
    "varsafe": {
      "type": "http",
      "url": "https://api.varsafe.dev/mcp"
    }
  }
}

Do not use ~/.claude/.mcp.json

That path is not read by Claude Code. User-scope servers live in ~/.claude.json (managed by claude mcp add --scope user); project-scope servers live in a .mcp.json file at the repository root.

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

json

{
  "mcpServers": {
    "varsafe": {
      "type": "url",
      "url": "https://api.varsafe.dev/mcp"
    }
  }
}

On the first tool call, your browser opens a consent screen. Pick your teams and scope preset, and you're connected.

No API token needed

MCP uses OAuth 2.1 — the agent handles authentication automatically. You don't need to create or paste API tokens.

Local Stdio Alternative

If you prefer to run the MCP server as a local subprocess — useful for air-gapped environments, inspection, or clients that don't support "type": "url" — use the @varsafe/mcp-server npm package.

1. Create an API token

In the dashboard, go to Team Settings → API Tokens → Create token. Copy the token — it's only shown once.

2. Add the local stdio config

Claude Code — run:

bash

claude mcp add --scope user --env VARSAFE_API_TOKEN=vs_at_... varsafe -- npx -y @varsafe/mcp-server

Or commit a project-scope .mcp.json at the repo root:

json

{
  "mcpServers": {
    "varsafe": {
      "command": "npx",
      "args": ["-y", "@varsafe/mcp-server"],
      "env": {
        "VARSAFE_API_TOKEN": "vs_at_..."
      }
    }
  }
}

Cursor — add to .cursor/mcp.json:

json

{
  "mcpServers": {
    "varsafe": {
      "command": "npx",
      "args": ["-y", "@varsafe/mcp-server"],
      "env": {
        "VARSAFE_API_TOKEN": "vs_at_..."
      }
    }
  }
}

3. Environment variables

Variable	Required	Default	Description
`VARSAFE_API_TOKEN`	Yes	—	varsafe API token (`vs_at_...`). `VARSAFE_TOKEN` is accepted as an alias.
`VARSAFE_API_URL`	No	`https://api.varsafe.dev`	Override the API base URL (self-hosted instances, staging, etc.).
`VARSAFE_MCP_DEBUG`	No	unset	When set to any truthy value, logs every API call to stderr.

Trade-offs

Hosted is faster to set up (no token), auto-refreshes, and gets new tools without any update. Preferred for most users.
Local stdio keeps the token under your control, works offline against self-hosted instances, and is inspectable — every file is readable in the @varsafe/mcp-server package on npm or GitHub.
Both share the same audit trail server-side, so you can switch freely.

When your AI tool connects for the first time, your browser opens a consent screen where you control exactly what the agent can access.

Scope Presets

Choose how much access to grant:

Preset	What the agent can do
Read Only	List projects, environments, and secret keys (no values)
Secrets Full	Everything in Read Only + read secret values, write secrets, export
Full Access	Everything in Secrets Full + audit log access

Granular Restrictions

You can further limit what the agent accesses:

Team selection — Choose which teams to grant access to
Project restrictions — Limit to specific projects within a team
Environment restrictions — Limit to specific environments (e.g., only development, never production)

When no project or environment restriction is set, the agent can access all projects and environments in the granted teams — subject to your own role permissions.

Client Verification

The consent screen shows whether the connecting client is a verified application:

Verified (green shield) — Pre-registered clients like Claude Code (Anthropic) and Cursor
Third-party — Dynamically registered MCP clients; review carefully before approving

Available Tools

The MCP server exposes 9 tools organized by capability:

Identity

Tool	Description	Required Scope
`varsafe_whoami`	View current identity, granted teams, and scopes	`identity:read`

Read (metadata only)

Tool	Description	Required Scope
`varsafe_list_projects`	List all projects in a team	`projects:read`
`varsafe_list_environments`	List environments in a project (name, slug, color)	`projects:read`
`varsafe_list_secrets`	List secret keys in an environment (no values)	`secrets:read`
`varsafe_diff_secrets`	Compare secret keys between two environments	`secrets:read`

Read (values) & Export

Tool	Description	Required Scope
`varsafe_get_secret_values`	List secrets with their decrypted values	`secrets:read_values`
`varsafe_export_secrets`	Export secrets as key-value pairs, with optional glob filter	`secrets:run`

Write

Tool	Description	Required Scope
`varsafe_set_secret`	Create or update a secret in an environment	`secrets:write`
`varsafe_unset_secret`	Delete a secret from an environment	`secrets:write`

Write tools modify real secrets

varsafe_set_secret and varsafe_unset_secret change your actual secrets. If you're using Full Access or Secrets Full presets, your AI agent can write to any environment it has access to — including production. Use environment restrictions to limit scope.

Scopes Reference

Scope	Description
`identity:read`	View user identity and granted teams
`projects:read`	List projects and environments
`secrets:read`	List secret keys and metadata (no values)
`secrets:read_values`	Read decrypted secret values
`secrets:write`	Create, update, and delete secrets
`secrets:run`	Export secrets for injection
`audit:read`	View audit logs

Managing Connections

Viewing Active Connections

Go to MCP Connections in the dashboard sidebar to see all active agent connections. Each connection shows:

Client name and verification status
Team access
Granted scopes
Connection date and last-used date

Revoking Access

Click Revoke on any connection to immediately disconnect the agent. The agent will need to re-authorize through the consent screen to reconnect.

Auto-Expiration

Connections that haven't been used for 90 days are automatically expired. Re-authorize by using the agent again — the consent flow will re-trigger.

Security Model

OAuth 2.1 with PKCE

MCP uses the OAuth 2.1 authorization code flow with Proof Key for Code Exchange (PKCE S256). This means:

No client secrets are stored on your machine
Authorization codes are single-use (5-minute expiry)
Access tokens are short-lived (1 hour) and auto-refreshed
Refresh tokens are rotated on every use (old tokens are invalidated)

Audit Trail

Every MCP tool call is logged in the audit trail, just like CLI and dashboard actions. You can see:

Which agent performed the action
Which team, project, and environment were accessed
The specific operation (list, read values, write, export)
Timestamp and IP address

Rate Limits

MCP tools are rate-limited per connection:

Category	Limit	Burst
Read operations	120/min	30
Write operations	60/min	15
Export operations	20/min	5

When rate-limited, the agent receives a 429 response with a Retry-After header.

Permission Boundaries

MCP grants are bounded by your own permissions:

If you're a Developer, the agent can't write to protected environments — even with secrets:write scope
If you restrict the grant to specific projects, the agent can't access other projects
Your role's access level is the ceiling; MCP scopes can only narrow it further

Example Workflows

Ask your agent to check for missing secrets

"Compare the secrets between staging and production for the api-backend project. Are there any keys missing in production?"

The agent uses varsafe_list_projects to find the project, then varsafe_diff_secrets to compare environments.

Set a secret from your editor

"Set the OPENAI_API_KEY to sk-proj-abc123 in the development environment of my api project."

The agent uses varsafe_set_secret to create or update the secret.

Export secrets for a local script

"Export all secrets matching DB_* from the staging environment."

The agent uses varsafe_export_secrets with the includePattern parameter to filter by glob.

Troubleshooting

"No MCP connections" after setup

The consent flow only triggers on the first tool call, not when the config is added. Ask your AI agent to do something with varsafe (e.g., "list my varsafe projects") to trigger the authorization.

Consent screen doesn't open

Make sure you're logged into the varsafe dashboard in the same browser that will handle the OAuth redirect. The MCP server redirects to your dashboard for consent.

Agent says "access denied" for a project

Check your grant restrictions. If you limited the grant to specific projects or environments during consent, the agent can't access anything outside those restrictions. Revoke the connection and re-authorize with broader access.

Agent stopped working after a while

Connections auto-expire after 90 days of inactivity. The agent will re-trigger the consent flow automatically — just use it again.

"Rate limit exceeded"

MCP tools are rate-limited. Wait for the Retry-After period and try again. If you're hitting limits regularly, batch your requests or space them out.

CLI Reference — Managing secrets from the command line
API Tokens — Programmatic access for CI/CD
Security Model — How your secrets stay safe
Core Concepts — Teams, projects, and environments

MCP Server (AI Agents) ​

Two Ways to Connect ​

How It Works (Hosted) ​

Quick Setup ​

Claude Code ​

Cursor ​

Local Stdio Alternative ​

1. Create an API token ​

2. Add the local stdio config ​

3. Environment variables ​

Trade-offs ​

Consent Screen ​

Scope Presets ​

Granular Restrictions ​

Client Verification ​

Available Tools ​

Identity ​

Read (metadata only) ​

Read (values) & Export ​

Write ​

Scopes Reference ​

Managing Connections ​

Viewing Active Connections ​

Revoking Access ​

Auto-Expiration ​

Security Model ​

OAuth 2.1 with PKCE ​

Audit Trail ​

Rate Limits ​

Permission Boundaries ​

Example Workflows ​

Ask your agent to check for missing secrets ​

Set a secret from your editor ​

Export secrets for a local script ​

Troubleshooting ​

Related Documentation ​

MCP Server (AI Agents)

Two Ways to Connect

How It Works (Hosted)

Quick Setup

Claude Code

Cursor

Local Stdio Alternative

1. Create an API token

2. Add the local stdio config

3. Environment variables

Trade-offs

Consent Screen

Scope Presets

Granular Restrictions

Client Verification

Available Tools

Identity

Read (metadata only)

Read (values) & Export

Write

Scopes Reference

Managing Connections

Viewing Active Connections

Revoking Access

Auto-Expiration

Security Model

OAuth 2.1 with PKCE

Audit Trail

Rate Limits

Permission Boundaries

Example Workflows

Ask your agent to check for missing secrets

Set a secret from your editor

Export secrets for a local script

Troubleshooting

Related Documentation