auth-mcp

A secure MCP server that stores all your API keys and auth credentials in one place, retrievable by any MCP client (Goose, Claude Code, Cursor, Codex, Gemini CLI...). Built with FastMCP so it can be hosted on Prefect Horizon and reached over HTTP at a URL like https://<name>.fastmcp.app/mcp.

Features

Tool	Description
auth_set(name, value, description)	Store or update a credential
auth_get(name, mask=True)	Retrieve a credential (masked by default; mask=False for full value)
auth_list()	List names + metadata only — never values
auth_search(query)	Search by name/description — metadata only
auth_recommend(task)	MCP sampling — asks goose's AI to pick the best credential for a task
auth_delete(name)	Delete a credential
auth_health()	Health check

Security model

• Encrypted at rest — the file backend encrypts every value with Fernet (AES-128-CBC + HMAC), key derived from AUTH_MCP_MASTER_KEY via PBKDF2-HMAC-SHA256 (600k iterations). The vault file never contains a plaintext secret.
• List/search never leak values — only names, descriptions and timestamps.
• Masked by default — auth_get returns ********last4 unless you explicitly pass mask=False.
• Remote access is authenticated by the hosting platform (FastMCP/Prefect Horizon).
• Optional prefect backend stores secrets as Prefect Cloud Secret blocks (durable, encrypted at rest by Prefect, RBAC-scoped) — ideal for the hosted deployment.

MCP sampling

auth_recommend(task) uses MCP sampling: the server sends the task plus a list of available credentials (names + descriptions only — values never leave the vault) back to goose's LLM, which returns the single best match and its reasoning. This turns the vault into a smart credential router:

auth_recommend(task="call OpenAI to summarize this email thread")
# -> {"ok": true, "recommendation": "openai",
#     "reasoning": "Task mentions OpenAI summarization.", "available": [...]}
# then:  auth_get(name="openai", mask=False)

Sampling is automatically available in goose (no configuration needed) and gracefully degrades — if the client doesn't support sampling, the tool returns the full list instead.

⚠️ Never commit .env, the vault file, or real keys. Everything sensitive is git-ignored.

Project layout

auth-mcp/
├── pyproject.toml            # deps + entry point (also used as Horizon "requirements")
├── README.md
├── .env.example              # copy to .env and fill in
├── src/auth_mcp/
│   ├── config.py             # env config (backend, master key, vault path)
│   ├── storage.py            # EncryptedFileStore + PrefectSecretStore backends
│   └── server.py             # FastMCP server + tools (Horizon server path)
└── tests/test_storage.py

Run locally

cd auth-mcp
python -m venv .venv
.venv\Scripts\activate            # Windows  (macOS/Linux: source .venv/bin/activate)
pip install -e ".[test]"

# generate a master key and run the server
set AUTH_MCP_MASTER_KEY=CHANGE-ME-strong-passphrase
python -m auth_mcp.server

Test it:

pytest -q

The server speaks MCP over stdio. Add it to your local Goose/Claude Code/Cursor config, then try:

auth_set(name="openai", value="sk-...", description="OpenAI API key")
auth_list()
auth_get(name="openai")            # -> ********1234
auth_get(name="openai", mask=False)

Deploy to Prefect Horizon

Prefect Horizon hosts FastMCP servers directly from a GitHub repo. Steps:

1. Push this project to GitHub

   cd auth-mcp
   git init && git add . && git commit -m "Initial auth-mcp"
   # create a repo on github.com and:
   git remote add origin git@github.com:<you>/auth-mcp.git
   git push -u origin main

2. Sign in to horizon.prefect.io (create an account if needed).

3. Create a new server and point it at your repo:

   • Repository: <you>/auth-mcp
   • Server path: src/auth_mcp/server.py
   • Requirements: pyproject.toml

4. Set environment variables in the Horizon UI:

   Variable	Value
   AUTH_MCP_MASTER_KEY	A strong passphrase (see below)
   AUTH_MCP_BACKEND	prefect (recommended for hosted: secrets live in Prefect Cloud)
   PREFECT_API_URL	https://api.prefect.cloud/api/accounts/<ACCOUNT_ID>/workspaces/<WORKSPACE_ID>
   PREFECT_API_KEY	A Prefect Cloud API key that can read/write Secret blocks

   Generate a master key:

   python -c "import secrets; print(secrets.token_urlsafe(32))"

5. Deploy, then copy your server URL, e.g. https://auth-mcp-xxxx.fastmcp.app/mcp.

6. Point your MCP client at the URL (HTTP transport):

   • Goose: goose mcp add auth-mcp --transport http https://auth-mcp-xxxx.fastmcp.app/mcp
   • Claude Code: claude mcp add auth-mcp --transport http https://auth-mcp-xxxx.fastmcp.app/mcp
   • Cursor: add to .cursor/mcp.json with "url": "https://auth-mcp-xxxx.fastmcp.app/mcp"

   Any client on your team can now read/write shared credentials through one hosted endpoint.

Backends

• file (default): encrypted vault on disk (AUTH_MCP_VAULT_PATH, default .auth_vault.json). Zero external services; good for local use and simple self-hosting.
• prefect: each credential is a Prefect Secret block. Install with pip install "auth-mcp[prefect]". Requires PREFECT_API_URL + PREFECT_API_KEY. Best for the Horizon deployment since secrets survive restarts and are managed by Prefect Cloud.

Security checklist

• Use a long, unique AUTH_MCP_MASTER_KEY and store it in a password manager
• Never commit .env or *.json vault files
• Grant the Horizon/Prefect API key only the permissions it needs (Secret blocks)
• Rotate keys regularly (auth_set overwrites in place)
• Keep mask=True unless a full value is genuinely required