KeyRing Setup Guide

KeyRing ships as part of the CoreforgedMCP gateway. Install it from PyPI.

Open your terminal (PowerShell on Windows, Terminal on Mac/Linux) and install:

pip install "coreforged-mcp>=1.4.0"

If you use a virtual environment or conda, activate it first. The package installs globally by default.

Verify the install:

coreforged-mcp --version

You should see a version number (e.g., coreforged-mcp 1.4.0). If you get "command not found," check that your Python Scripts directory is on your PATH.

The gateway needs to be registered in your AI tool's MCP configuration file. This tells Claude Code or Claude Desktop to start the gateway when it launches.

For Claude Code

Navigate to your project directory and run:

coreforged-mcp init

This creates or updates .mcp.json in the current directory:

{
  "mcpServers": {
    "coreforged": {
      "command": "coreforged-mcp",
      "args": ["run"]
    }
  }
}

Restart Claude Code. The gateway starts automatically.

For Claude Desktop

Open the configuration file at:

Add the same "coreforged" server entry inside the "mcpServers" block. Save and restart Claude Desktop.

Verify it worked:

coreforged-mcp status

You should see "Discovered plugins: 1" with KeyRing listed.

Before you can put keys on the ring, you need to know where they are. API keys tend to scatter across your filesystem — .env files, JSON credential files, plain text files in config directories.

What you're looking for:

• .env files with KEY=value pairs
• JSON files named client_secret_*.json or credentials.json (Google OAuth)
• Firebase service account JSON files
• Plain text files containing a single API key

Common services and their key formats:

Now that you know where your keys are, add them to KeyRing's encrypted store.

Create the KeyRing directory:

mkdir %USERPROFILE%\.coreforged\keyring

mkdir -p ~/.coreforged/keyring

Create the secrets file at ~/.coreforged/keyring/.secrets.json:

{
  "openai-api-key": {
    "value": "sk-your-actual-key-here",
    "service": "openai",
    "description": "OpenAI API key for GPT calls"
  },
  "github-pat": {
    "value": "ghp_your-actual-token-here",
    "service": "github",
    "description": "GitHub personal access token"
  }
}

Save the file, then trigger auto-encryption:

coreforged-mcp status

The first read auto-migrates to encrypted format using a machine-local master key at ~/.coreforged/keyring/.master_key. The plaintext is gone after migration.

KeyRing checks where a request goes before it sends the key.

A service KeyRing knows always goes to its own API host. If your agent passes another URL for one of these services, KeyRing ignores it.

For any other service, mark the key custom and bind it to exact hosts. KeyRing refuses the request otherwise. Add the key to the ring first (Section 4), then bind it:

coreforged-mcp keyring bind my-service-key api.your-service.com --custom

Your agent then passes the URL as base_url in the request's params. KeyRing sends the key only if the URL uses https and its host is one you bound. Each bind call adds to the hosts already bound. unbind takes hosts off again: it removes the hosts you name, or clears the binding if you name none.

coreforged-mcp keyring unbind my-service-key api.your-service.com

A key you marked custom stays custom, so with no binding KeyRing refuses it until you bind a host again. If you name every host, the binding becomes an empty list (the command prints -> []), and KeyRing refuses the key for every host. To clear a binding, name no host.

You can bind a key for a known service too. KeyRing then refuses the call unless that service's host is in the binding.

The commands coreforged-mcp allow-domain, remove-domain and list-domains edit and show a list in allowed_domains.json. No request reads that list, so they do not change where a key can go.

Once configured, your AI agent accesses secrets through two MCP tools.

Test it:

1. Start a Claude Code session in a project with the gateway configured
2. Ask: "What secrets are available on my KeyRing?"
3. Ask: "Use my OpenAI key to list available models."

Adding a new key:

• Use the setup wizard: coreforged-mcp setup
• Or re-consolidate from new directories: coreforged-mcp consolidate --dir ~/new-project

Rotating a key:

1. Update the key at the service (e.g., regenerate your OpenAI key)
2. Update the key in your .env file
3. Run coreforged-mcp consolidate — it detects the changed value and updates the ring

Back up these files:

Store backups in a secure location (password manager, encrypted drive). Never commit these to git.