Stable MCP

Stable MCP is a local MCP client and proxy. It keeps remote server credentials alive and gives Codex and Claude one stable local endpoint.

Development

Requires Crystal 1.21 or newer.

shards install
make run

Open http://127.0.0.1:7741. Run make check before committing.

Create or enter the master password in the browser. Until the vault is unlocked, only the unlock form and health endpoint are available. Configuration is stored in data/stable-mpc.db, and connector credentials are encrypted with a key derived from the master password. STABLE_MPC_MASTER_PASSWORD remains available for unattended startup.

Current support

• Add HTTPS or explicit localhost HTTP MCP servers.
• Connect to unauthenticated Streamable HTTP servers and sync paginated tool definitions.
• Discover OAuth capabilities while entering a server URL, then use automatic DCR, hosted CIMD, supplied OAuth 2.1 credentials, or an encrypted bearer token.
• Refresh expired access tokens with atomic refresh-token rotation while the refresh token remains valid.
• Show persisted credential health and run an explicit authentication diagnostic without exposing upstream response bodies.
• Group and filter discovered tools by title or name, then allow or forbid each tool. New tools are allowed by default.
• Use separate Overview, Tools, and Settings tabs for each server; upstream settings can change without changing its local slug.
• Connect Codex or Claude Code with separate bearer tokens to the local /mcp/:slug endpoint, with JSON or SSE responses.
• Track each client's request count and recent activity, then rotate its token independently.

Legacy HTTP+SSE upstreams and signed/notarized release automation remain in the roadmap.

macOS Start at Login

Open Settings, choose Store master password in Keychain, then enable Start at Login. The app copies the current binary into ~/Library/Application Support/Stable MCP and installs a per-user LaunchAgent for the next login. The LaunchAgent plist never contains the password.

Settings can also change the master password. Stored credentials are re-encrypted in one database transaction. Local client tokens and active connector sessions are preserved.

Build a self-contained archive for the current Mac architecture with make package-macos.