Agent Keyring

An MCP server that holds secrets and makes authenticated API calls on behalf of AI agents — so API keys never enter conversation context.

Agent → Keyring MCP → retrieve secret → make API call → return data only

The agent says what to do ("query GA4 for sessions"). The keyring handles how to authenticate. Keys stay on the keyring, never in the agent's mouth.

Quickstart

# 1. Clone
git clone https://github.com/MithrynMarious/agent-keyring.git
cd agent-keyring

# 2. Create a virtual environment and install
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install .

# 3. Copy the skeleton and fill in your keys
cp .secrets.skeleton.json .secrets.json
# Edit .secrets.json — replace placeholders with real values

# 4. Add to your MCP config (.mcp.json or Claude Desktop settings)

Add to your MCP config file:

Claude Code — .mcp.json in your project root:

{
  "mcpServers": {
    "keyring": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/path/to/agent-keyring"
    }
  }
}

Claude Desktop — config file location varies by OS:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Same JSON format — add the keyring entry to your existing mcpServers block.

# 5. Verify
python -c "from secret_store import LocalFileStore; s = LocalFileStore('.secrets.json'); print(f'{len(s.list_names())} secrets loaded')"

Related MCP server: keyvault

What's Working

MCP Tools

Security Model (DC-1)

Secret values never appear in:

• MCP tool results

• Conversation context

• Log output

• EAM entries or session records

The keyring makes the authenticated API call and returns only the response data. The checkout ledger logs every access (who, what, when, why) without recording the secret value.

Docs

• SETUP.md — Full setup guide with GCP migration, troubleshooting, and embedded lessons from prior setups

• FRICTION_JOURNAL.md — GCP console gotchas (training-data-vs-reality deltas)

• AGENTS.md — Engineering posture and conventions

Populating Secrets

Bootstrap (recommended — one command)

Scan a machine for scattered credentials, collect them, and populate the keyring:

python consolidate.py bootstrap ~/projects ~/.config ~/keys
# Scans → migrates → ingests → validates. Values stay on disk, never in stdout.

Add --dry-run to preview without changing anything. DC-1 safe: the bootstrap prints filenames and counts, never secret values.

Manual paths

# Interactive (value from stdin, never CLI args)
python add_secret.py my-api-key

# From files
mkdir -p .secrets
# Place key files in .secrets/
python consolidate.py ingest

# Bulk discovery
python consolidate.py scan ~/projects    # find scattered creds
python consolidate.py migrate ~/projects --target .secrets/

GCP Backend (Multi-Machine)

For shared secrets across machines, use GCP Secret Manager as the backend:

{
  "mcpServers": {
    "keyring": {
      "command": "python",
      "args": ["server.py"],
      "env": { "KEYRING_GCP_PROJECT": "your-project-id" }
    }
  }
}

See SETUP.md Option B for the full GCP walkthrough.

Registering Agents

New agents are denied access by default (DC-1). To grant an agent access to secrets, add an entry to permissions.json:

{
  "agent-name@agentmail.to": ["secret-name-1", "secret-name-2"],
  "admin-agent@agentmail.to": ["*"],
  "_default": []
}

• Each key is an agent identifier (AgentMail address or DID)

• Values list the secret names the agent can check out

• "*" grants access to all secrets

• "_default": [] means unregistered agents get nothing — this is the DC-1 structural default

When an unregistered agent calls keyring_list_available, it sees an empty list. The checkout ledger still records the attempt.

Environment Variables

See .env.example for the complete list. Key variables:

Logging

The server uses Python's logging module. Set the log level via environment:

# See all keyring activity
LOGLEVEL=DEBUG python server.py

# Quiet mode (errors only)
LOGLEVEL=ERROR python server.py

Default level is WARNING. The keyring.store and keyring.ledger loggers are the most useful for debugging auth and access issues.

Troubleshooting

For GCP-specific setup issues, see SETUP.md and FRICTION_JOURNAL.md.

Docker

# Local file store
docker compose up keyring

# GCP backend
KEYRING_GCP_PROJECT=your-project docker compose --profile gcp up keyring-gcp

Mount your .secrets.json and permissions.json as volumes. See docker-compose.yml for the full configuration.

CI

Tests run on push and PR via GitHub Actions across Python 3.12–3.13 on Linux, Windows, and macOS. See .github/workflows/test.yml.

License

Proprietary — CoreForged LLC. See LICENSE for terms.