ScopeHold MCP Server

@scopehold/mcp is a local stdio MCP server that gives AI coding agents scoped, audited access to credentials managed in ScopeHold.

Your agent gets exactly two tools:

• list_available_secrets — metadata-only inventory of the secrets this Agent Key can resolve. Never returns values, usernames, passwords, or login URLs.
• resolve_secret — resolves one directly granted secret through the ScopeHold API.

The trust boundary stays with ScopeHold: every call goes through the same API used by the ScopeHold CLI, so per-agent grants, audit events (including inventory reads), billing limits, and rate limits apply unchanged. This process never stores credentials and never logs resolved values — the smoke test asserts it.

Quick start

You need an Agent Key (agt_...), created in ScopeHold when you add an agent to a project.

SCOPEHOLD_API_URL=https://api.scopehold.com \
SCOPEHOLD_AGENT_TOKEN=<agent-key> \
npx @scopehold/mcp

Claude Code

claude mcp add scopehold --env SCOPEHOLD_API_URL=https://api.scopehold.com --env SCOPEHOLD_AGENT_TOKEN=<agent-key> -- npx -y @scopehold/mcp

Cursor

{
  "mcpServers": {
    "scopehold": {
      "command": "npx",
      "args": ["-y", "@scopehold/mcp"],
      "env": {
        "SCOPEHOLD_API_URL": "https://api.scopehold.com",
        "SCOPEHOLD_AGENT_TOKEN": "<agent-key>"
      }
    }
  }
}

Generic MCP config

{
  "servers": {
    "scopehold": {
      "command": "npx",
      "args": ["-y", "@scopehold/mcp"],
      "env": {
        "SCOPEHOLD_API_URL": "https://api.scopehold.com",
        "SCOPEHOLD_AGENT_TOKEN": "<agent-key>"
      }
    }
  }
}

Tool reference

list_available_secrets

No arguments. Returns the agent identity and metadata (provider, name, environment, kind, scopeKind, version, timestamps) for each secret the Agent Key can resolve. Inventory responses are sanitized field-by-field client-side as defense in depth — values can never pass through, and inventory reads are themselves audited server-side.

resolve_secret

| Argument | Required | Description | | --- | --- | --- | | provider | yes | Exact provider slug from list_available_secrets | | name | yes | Exact secret name from list_available_secrets | | environment | no | Exact environment from list_available_secrets |

Returns the same payload as the ScopeHold /resolve API: API-key secrets include a value; login credentials include a credentials object. Denials mirror the API's responses, and every resolve (successful or denied) appears in your workspace audit log attributed to the named agent.

When to use scopehold exec instead

resolve_secret returns the raw value into the agent's context. When a command can receive secrets through environment variables, prefer scopehold exec from the ScopeHold CLI — it injects values into the process environment and keeps them out of the model context entirely. A sensible default: use this MCP server for inventory and the occasional explicit resolve; use exec for running things.

Security model

• The Agent Key is the only credential this process holds, supplied via environment variable. It is revocable in ScopeHold at any time and scoped to the grants you chose.
• Secrets are resolved at request time and never written to disk or logged by this process.
• All authorization decisions happen server-side in ScopeHold; this package contains no policy logic to misconfigure.
• The smoke test (npm test) runs a mock API that deliberately injects leak canaries and asserts they appear in neither tool output nor stderr.

Found a security issue? Please email [email protected] rather than opening a public issue.

Development

npm install
npm run typecheck
npm run build
npm test

License

MIT