Integrations

MCP Server Integration

@secr/mcp is a Model Context Protocol server that gives AI coding agents direct access to your secrets. Instead of manually running secr pull or maintaining .env files, agents can read, write, and manage secrets through MCP tool calls.

Quick Start

1. Create an agent token

Terminal

secr agents create --name "claude-code" --scope "read:secrets,write:secrets"
# → secr_agent_abc123...

2. Add the MCP server

Claude Code

Terminal

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

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" }
    }
  }
}

3. Start using it

Ask your agent “what secrets do we have?” or “set the Stripe key to sk_live_...”. The agent calls secr tools automatically.

Tools Reference

The server exposes 5 tools. All tools accept optional org, project, and environment parameters that override configured defaults.

get_secret

Get a single secret value by key.

Parameter	Type	Required	Description
key	string	Yes	The secret key name to retrieve
org	string	No	Organization slug
project	string	No	Project slug
environment	string	No	Environment slug

Returns the secret in KEY=value format. Returns an error if the key is not found.

list_secrets

List secret key names without values.

Parameter	Type	Required	Description
search	string	No	Filter keys by search term
org	string	No	Organization slug
project	string	No	Project slug
environment	string	No	Environment slug

Returns key names, one per line. Includes descriptions when available.

set_secret

Create or update a secret.

Parameter	Type	Required	Description
key	string	Yes	The secret key name
value	string	Yes	The secret value
org	string	No	Organization slug
project	string	No	Project slug
environment	string	No	Environment slug

Returns the key name and new version number.

delete_secret

Delete a secret.

Parameter	Type	Required	Description
key	string	Yes	The secret key name to delete
org	string	No	Organization slug
project	string	No	Project slug
environment	string	No	Environment slug

list_environments

List all environments for a project.

Parameter	Type	Required	Description
org	string	No	Organization slug
project	string	No	Project slug

Returns environment slugs and names.

Configuration

Environment Variables

Parameter	Type	Required	Description
SECR_TOKEN	string	Yes	Agent token (secr_agent_...). Required.
SECR_ORG	string	.secr.json	Organization slug.
SECR_PROJECT	string	.secr.json	Project slug.
SECR_ENVIRONMENT	string	.secr.json	Default environment slug.
SECR_API_URL	string	https://api.secr.dev	API base URL (for self-hosted).

Parameter Resolution

All tools resolve org, project, and environment in this order:

Explicit tool argument — passed by the agent in the tool call
Environment variable — SECR_ORG, SECR_PROJECT, SECR_ENVIRONMENT
.secr.json — project config file from secr init

If your project has a .secr.json, tools can be called with just the required params (e.g. key) and everything else resolves automatically.

Security

Agent Tokens

Use scoped agent tokens instead of personal CLI tokens. Agent tokens have explicit permissions that limit what the MCP server can do.

Terminal

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

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

Token Storage

•Claude Code — stored in Claude's MCP config, not in project files
•Cursor — store in ~/.cursor/mcp.json (user-level, not committed)
•VS Code — use .vscode/mcp.json and add it to .gitignore, or use user-level settings

Never commit agent tokens to source control.

Audit Trail

All operations through the MCP server are logged in secr's audit log, tagged with the agent identity. View them with:

secr log

Troubleshooting

Error	Cause	Fix
SECR_TOKEN environment variable is required	Token not set in MCP server env config.	Pass SECR_TOKEN in the env config for the MCP server.
Missing org	No org configured and not passed in tool call.	Set SECR_ORG env var or run secr init in the project.
Missing project	No project configured and not passed in tool call.	Set SECR_PROJECT env var or run secr init.
API error: Forbidden	Agent token lacks the required scope.	Create a new token with the needed scope (e.g. write:secrets).
Secret "X" not found	The key doesn't exist in the target environment.	Check spelling or use list_secrets to see available keys.

AI agents + secr = fast and secure

claude mcp add secr -- npx @secr/mcp

Create Free Account Read: MCP Server Guide