Skip to content
  1. Home
  2. Docs
  3. MCP Setup
Back to docs
Documentation

MCP Setup

Add q-ring as an MCP server so AI agents can manage secrets natively - same single binary, every host. New to q-ring? Start with Getting Started.

Server config

Configure MCP

Point your editor at the qring-mcp binary. Config snippets for every supported host.

Since v0.15, qring setup cursor (or kiro / claude) writes these configs for you - merged non-destructively, so existing servers are preserved. The snippets below are the manual equivalent.

Diagram: your AI editor talks to the q-ring airlock, which applies policy.wrap rules, strips the environment of spawned servers, scrubs known secret values (whole or encoded) from results, errors and progress, and audits every call before anything reaches the third-party MCP server.

Since v0.16, q-ring can also stand between your agent and other MCP servers: qring mcp wrap -- npx some-mcp-server runs a third-party server behind the airlock - spawned with a stripped environment and every tool call audited, with tool arguments deliberately never logged. Since v0.17.5 the airlock also proxies resources and prompts, wraps remote servers with --url, scrubs known secret values from every result, and enforces the project's policy.wrap rules - allow/deny globs, approval-gated tools, rate limits. Since v0.19 the scrub covers errors, progress messages and URIs too, matches each value whole and in its base64, hex, URL and JSON-escaped forms, and replaces it with a token that names the key, such as [QRING:REDACTED:GITHUB_TOKEN]. Unlike qring exec, the airlock never matches partial slices of a secret: an agent could otherwise read one out a character at a time through a tool that echoes its input. If redaction cannot be set up, results are withheld.

The q-ring server also exposes read-only MCP resources, so state an agent should look at costs no extra tools (still 46). Every resource is JSON, never contains a secret value, and goes dark when .q-ring.json policy denies the tool that exposes the same information.

  • qring://sessions - Per-agent session summaries from the audit chain, last 7 days (canary trips stripped; hidden when audit_log is denied)
  • qring://sessions/{id} - One session's event timeline, key names and actions only
  • qring://policy - The active .q-ring.json policy as the agent may see it; says so when there is none or the file is corrupt (hidden when get_policy_summary is denied)
  • qring://rotation - The rotate:due --all list: scheduled secrets with state, interval and due date, most overdue first (hidden when list_secrets is denied)
  • qring://canaries - Planted canaries with trip counts and alert channels; off by default, listed only when the server starts with QRING_MCP_EXPOSE_CANARIES=1

Cursor / Kiro

.cursor/mcp.json
{
  "mcpServers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

Claude Code

.mcp.json (or install the plugin)
// Fastest: the native plugin (MCP + commands + skills + hooks)
//   /plugin marketplace add I4cTime/q-ring
//   /plugin install qring@q-ring
// Or MCP-only via project .mcp.json:
{
  "mcpServers": {
    "q-ring": {
      "type": "stdio",
      "command": "qring-mcp"
    }
  }
}

VS Code

.vscode/mcp.json
{
  "servers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

Optional

Editor Plugins

One install that pre-wires Cursor, Kiro, or Claude Code with the full q-ring toolkit.

The q-ring editor plugins bundle rules, skills, agents, slash commands, hooks, and the MCP connector - pre-wired to the 46 tools, packaged natively for each editor (Cursor rules, Kiro steering docs, Claude Code skills plus a SessionStart hook that loads the always-on rules).

3 Rules

Always-on guidance: secret hygiene, q-ring workflow, and .env file safety.

5 Skills

Auto-triggered by context: management, scanning, rotation, exec-with-secrets, and project onboarding (Claude Code adds a sixth carrying the always-on rules).

2 Agents

Security auditor for proactive monitoring and secret-ops for daily management.

8 Commands

Slash commands for the most common operator tasks: scan, rotate, validate, exec, teleport, and more.

3 Hooks

After-file-edit scan, session-start project context loading, and a pre-shell guard against exposing .env files.

MCP Connector

Auto-connects to qring-mcp via stdio. All 46 tools available in-IDE.

install
# One command per editor:
$ qring setup cursor # or kiro / claude
# Claude Code marketplace, or manual build from a checkout:
$ /plugin marketplace add I4cTime/q-ring
$ pnpm run plugin:sync

MCP cookbook

Prompt cookbook

Every MCP tool with a one-sentence prompt example you can paste into any agent chat.

get_secret

Retrieve `OPENAI_API_KEY` from project scope for `prod` and return just the raw value.

promote_secret

Promote `DATABASE_URL` from `staging` to `prod`, and tell me first if prod already holds a different value.

diff_environments

Compare `staging` and `prod` key by key and list what differs or is missing on one side - statuses only, no values.

list_secrets

List project secrets tagged `payments` and show only stale entries matching `STRIPE_*`.

set_secret

Set `STRIPE_SECRET_KEY` in project scope with tags `payments,prod` and a TTL of 86400 seconds.

delete_secret

Delete `LEGACY_TOKEN` from global scope and confirm whether it existed.

has_secret

Check whether `GITHUB_TOKEN` exists in project scope and return true/false.

export_secrets

Export only `OPENAI_API_KEY` and `STRIPE_KEY` as `.env` for `prod`.

import_dotenv

Import this `.env` content into project scope in dry-run mode and report what would change.

check_project

Validate `.q-ring.json` at this path and show missing, stale, and expired required keys.

env_generate

Generate `.env` content from the project manifest for `staging` without writing files.

inspect_secret

Inspect `DB_PASSWORD` and summarize scope, decay state, tags, and entanglement metadata.

detect_environment

Detect current environment for this project path and include the detection source.

generate_secret

Generate an `api-key` with prefix `sk-` and save it as `OPENAI_API_KEY` in project scope.

entangle_secrets

Entangle `API_KEY` in this project with `API_KEY_BACKUP` in another project path.

disentangle_secrets

Remove entanglement between `API_KEY` and `API_KEY_BACKUP` and confirm success.

tunnel_create

Create an ephemeral tunnel value with TTL 300 and maxReads 1, then return the tunnel ID.

tunnel_read

Read tunnel `tun_abc123` once and return value or not-found/expired status.

tunnel_list

List all active tunnels with read counts and time remaining.

tunnel_destroy

Destroy tunnel `tun_abc123` immediately and confirm whether it existed.

teleport_pack

Pack keys `OPENAI_API_KEY` and `STRIPE_KEY` into an encrypted bundle using this passphrase.

teleport_unpack

Unpack this teleport bundle in dry-run mode and list keys and scopes that would be imported.

audit_log

Return last 100 `read` audit events for `OPENAI_API_KEY` in reverse chronological order.

detect_anomalies

Detect anomalies for `OPENAI_API_KEY` and include recommendations.

health_check

Run a project-scope health check and summarize healthy/stale/expired plus anomaly count.

validate_secret

Validate `OPENAI_API_KEY` with provider auto-detection and return provider + latency.

list_providers

List available validation providers with descriptions and known key prefixes.

register_hook

Register an HTTP hook for `DB_PASSWORD` rotate events to this URL with a clear description.

list_hooks

List all registered hooks and include type, match criteria, and enabled status.

remove_hook

Remove hook `hk_abc123` and return a not-found error if it does not exist.

exec_with_secrets

Run `npm test` with only `OPENAI_API_KEY` injected using restricted profile.

scan_codebase_for_secrets

Scan `./src` for hardcoded secrets and return file, line, key name, and entropy.

get_project_context

Return redacted project context for this path including manifest and recent actions.

agent_remember

Remember the note `rotated Stripe keys after release` under key `release_notes`.

agent_recall

Recall key `release_notes`; if omitted, list all memory keys and update times.

agent_forget

Forget memory key `release_notes` and report whether it was present.

lint_files

Lint these files for hardcoded secrets in fix mode and return structured fix results.

analyze_secrets

Analyze project secrets for unused keys, stale entries, and top read frequency.

status_dashboard

Start the live status dashboard on port 9876 and return the local URL - page surfaces KPIs, manifest gaps, policy posture, approvals, hooks, anomalies, and a filterable 24h audit feed without ever rendering secret values.

agent_scan

Run one agent scan with auto-rotate enabled across these project paths and return report JSON.

verify_audit_chain

Verify audit hash-chain integrity and show first break location if tampering is detected.

export_audit

Export audit events as JSON from 2026-03-01 until now.

rotate_secret

Attempt provider-native rotation for `OPENAI_API_KEY` and store the new value if rotated.

ci_validate_secrets

Run CI batch validation for project scope and return pass/fail summary JSON.

check_policy

Check whether command `npm publish` is allowed by exec policy for this project path.

get_policy_summary

Return governance policy summary for this project, including tool and secret lifecycle rules.