Integration

Give Your AI Agent Direct Access to Secrets

AI coding agents are powerful, but they still can't access your secrets without you copy-pasting values into the chat. The secr MCP server fixes this — your agent gets scoped, audited access to secrets via the Model Context Protocol, with zero secrets in prompts or files.

The Problem

You're building a feature that needs a database URL. Your AI agent asks for it. What do you do?

Paste the connection string into the chat? Now it's in the conversation history.
Tell the agent to read .env? Now it's in the context window.
Manually run secr pull and tell the agent the value? Tedious and error-prone.

With MCP, the agent calls a tool. The tool fetches the secret from secr's API using a scoped token. The value goes straight to the agent's working memory — never stored in chat history, never written to disk.

How It Works

The secr MCP server runs as a stdio subprocess spawned by your AI tool. It connects to the secr API using an agent token and exposes 5 tools:

Tool	What It Does
get_secret	Fetch a single secret value by key
list_secrets	List key names (no values) with optional search
set_secret	Create or update a secret
delete_secret	Delete a secret
list_environments	List environments for a project

The agent decides which tool to call based on your conversation. Ask “what secrets do we have in staging?” and it calls list_secrets. Say “set the Stripe key to sk_live_...” and it calls set_secret.

Setup in 2 Minutes

1. Create an agent token

Agent tokens are scoped — you control exactly what the agent can access.

Terminal

# Read-only (recommended to start)
secr agents create --name "claude-code" --scope "read:secrets"

# Read-write for full workflow
secr agents create --name "claude-code" --scope "read:secrets,write:secrets"

# → secr_agent_abc123...

2. Connect to your AI tool

Claude Code

Terminal

claude mcp add secr -e SECR_TOKEN=secr_agent_xxx -- npx @secr/mcp

That's it. Claude Code will start the MCP server automatically in every session.

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "secr": {
      "command": "npx",
      "args": ["@secr/mcp"],
      "env": { "SECR_TOKEN": "secr_agent_xxx" }
    }
  }
}

VS Code / Copilot

.vscode/mcp.json

{
  "servers": {
    "secr": {
      "command": "npx",
      "args": ["@secr/mcp"],
      "env": { "SECR_TOKEN": "secr_agent_xxx" }
    }
  }
}

Don't commit tokens

If using .vscode/mcp.json, add it to .gitignore. Or use VS Code's user-level settings instead of workspace settings.

Real Workflows

Here's what working with the MCP server actually looks like:

“What's the database URL?”

Agent calls get_secret with key: "DATABASE_URL" and returns the value. No copy-paste, no .env file.

“Add a Stripe webhook secret”

What the agent does

# Agent calls set_secret:
#   key: "STRIPE_WEBHOOK_SECRET"
#   value: "whsec_..."
#   environment: "development"
#
# Then uses process.env.STRIPE_WEBHOOK_SECRET in code

“What environments do we have?”

Agent calls list_environments and gets back development, staging, production. Now it knows which environment to target.

“Show me all the API keys”

Agent calls list_secrets with search: "API" and lists matching key names — without exposing values.

Security Model

Giving an AI agent access to secrets sounds risky. Here's why it's actually safer than the alternatives:

Scoped tokens

Agent tokens have explicit permissions. A read-only token can't write or delete secrets.

Full audit trail

Every MCP tool call hits the secr API and is logged with the agent identity, timestamp, and action.

No secrets on disk

Secrets are fetched on-demand via API. No .env files, no local copies, no accidental commits.

Revocable access

Compromised token? Revoke it instantly. The agent loses access immediately.

Compare: .env files vs MCP

With .env files, every developer (and every AI agent) has a plaintext copy of every secret on their machine. With MCP, secrets are fetched on demand through a scoped, audited, revocable channel.

Configuration

The MCP server resolves org, project, and environment from three sources, in order:

Tool arguments — the agent passes them explicitly in the call
Environment variables — SECR_ORG, SECR_PROJECT, SECR_ENVIRONMENT
.secr.json — project config from secr init

If your project has a .secr.json from secr init, the agent can call tools with just a key — no need to specify org/project/environment every time.

Combine with Agent Rules

MCP gives your agent access to secrets. Agent rules (CLAUDE.md, .cursorrules) teach it how to use them. Use both together:

CLAUDE.md

## Secrets Management

This project uses secr for secrets. You have access to the secr MCP server.

### Rules
- Use the secr MCP tools to read and manage secrets.
- NEVER hardcode secret values in source files.
- NEVER create or modify .env files.
- Use `get_secret` to look up values you need.
- Use `set_secret` when adding new service credentials.
- Reference secrets in code as `process.env.KEY_NAME`.

### Workflow
1. Need a secret value? Call `get_secret` with the key name.
2. Adding a new service? Call `set_secret` to store the credential, then
   reference `process.env.KEY_NAME` in code.
3. Not sure what secrets exist? Call `list_secrets` to see available keys.

See the full AI Agent Guide for rules files for Claude Code, Cursor, Copilot, and Windsurf.

Secrets management that works with your AI tools

Set up the MCP server once. Every agent session gets secure, scoped, audited access to secrets.

Create Free Account Read the Docs