Home
Docs
MCP Setup

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.

Cursor / Kiro

{
  "mcpServers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

Claude Code

// 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

{
  "servers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

Optional

Cursor Plugin

One install that pre-wires Cursor with the full q-ring toolkit.

The q-ring Cursor Plugin bundles rules, skills, agents, slash commands, hooks, and the MCP connector — pre-wired to the 44 tools.

3 Rules

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

5 Skills

Auto-triggered: management, scanning, rotation, exec, onboarding.

2 Agents

Security auditor and day-to-day secret-ops assistant.

8 Commands

Slash commands for scan, rotate, validate, exec, teleport, and more.

2 Hooks

After-file-edit scan and session-start project context.

MCP Connector

Auto-connects to qring-mcp — all 44 tools available.

manual install

# Install from Cursor marketplace, or manually:
$ cp -r cursor-plugin/ ~/.cursor/plugins/qring/

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.

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 `tu_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 `tu_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

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 `node scripts/smoke.js` 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.