MCP Server (AI Agents)

Give AI coding assistants scoped, audited access to your secrets — hosted OAuth 2.1 endpoint or local stdio server, nine tools, per-team grants.

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:

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

How It Works (Hosted)

1. Discover — Your AI tool reads the MCP server URL and discovers OAuth endpoints automatically
2. Consent — Your browser opens a consent screen where you choose teams, scopes, and optional restrictions
3. Authorize — The agent receives an OAuth 2.1 access token (PKCE-secured, 1-hour expiry, auto-refreshed)
4. 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:

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:

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

Cursor

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

{
  "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.

Local Stdio Alternative

If you prefer to run the MCP server as a local subprocess — useful for self-hosted instances, inspection, or clients that don’t support "type": "url" — use the @varsafe/mcp-server npm package (it also installs a varsafe-mcp binary if you prefer a global install over npx).

1. Create an API token

In the dashboard, go to API Tokens, select the team, and click Create token. Copy the token — it’s only shown once.

2. Add the local stdio config

Claude Code — run:

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:

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

Cursor — add to .cursor/mcp.json:

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

3. Environment variables

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.

Consent Screen

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:

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

Read (metadata only)

Read (values) & Export

Write

Scopes Reference

Managing Connections

Viewing Active Connections

Go to MCP 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:

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

Related Documentation

• 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