Portunus MCP server

Portunus

<!-- shared:tagline -->

A secret broker that finds secrets by metadata and injects them — without them ever touching your LLM. Free & open source.

<!-- /shared:tagline --> <!-- shared:byline --> Built by Mathew Dostal — fractional CTO, Dostal Technology. <!-- /shared:byline -->

Choose your vault. Give your AI agents safe tooling to use it — without secrets ever touching

the LLM.

portunus is a thin broker between your AI agents and the secret vault you already run. It doesn't store your secrets or reinvent vault security — it resolves them by metadata and injects them at the boundary, so an agent can use a secret (call an API, deploy, sign) without the raw value ever landing in the model's context, logs, or tool output.

(Portunus — the Roman god of keys and doors. Fitting.)

Get your agent using it in one command

curl -fsSL https://mdostal.github.io/portunus/install.sh | bash

Installs the CLI, wires the MCP server into whatever AI coding agent CLIs are already on the machine (Claude Code, Codex CLI today), and drops in the usage skills — so an agent gets the boundary-only usage conventions immediately, not just a raw tool list. Already have portunus installed? Just run portunus agent init — same thing, idempotent, safe to re-run any time (e.g. after installing a new harness). portunus agent status shows what's currently wired without changing anything.

Since this runs standalone often — a local key-value store on its own, not just a plugin — it keeps itself current too: portunus update check (read-only) / portunus update run (installs, with either an interactive confirm or --yes) walk the same "your own already-authenticated gh CLI, pinned to an exact release tag, never a silent unattended swap" posture as the desktop app's updater. A one-line stderr heads-up ("portunus vX.Y.Z is available…") shows up on its own, throttled to once a day, never installs anything by itself — opt out any time with PORTUNUSNOUPDATE_CHECK=1.

portunus site → — landing page, install snippets, and the component-model pitch in one place.

Documentation → — quickstart, concepts, architecture, CLI/MCP reference, and Process & Design, the design record behind every feature, published from .pHive/ and rebuilt on every push to main.

The problem

AI agents need real secrets to do real work — deploy tokens, API keys, DB creds. But the moment a secret touches an LLM's context, a log line, or a tool result, it's leaked. Most teams already have a vault. What's missing is the layer that lets an agent use that vault safely.

That's portunus.

What works today

Shortened. The full README is on GitHub.