Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@agentry-mcp search the registry for a code review agent"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that drives the agentry CLI already installed on your
machine, so a coding agent (Claude Code, Codex or any MCP host) can search a
registry, read a QuickAgent's capability contract, verify a release, check the
machine, install and remove QuickAgents, run them and hold an interactive
session with one. Tool results are the CLI's own JSON. Anything that writes or
runs asks for the same consent the CLI asks for on a terminal.
It is a local stdio server written in TypeScript on the official
@modelcontextprotocol/sdk.
It bundles no CLI: the login, consent memory and runner policy are the
CLI's.
Node 20 or newer.
The agentry CLI on the machine, found through AGENTRY_BIN or PATH
(see the CLI documentation). The
server runs agentry --version at start and refuses to start below
MIN_CLI_VERSION (src/cli.ts) or without install --plan and
run --plan.
Signing in (agentry login) is done once in a terminal; the server uses
that login and never sees the token.
Related MCP server: gaiadesk-mcp
npm ci
npm run build # tsc into dist/
npm test # builds, then runs the tests against a fake agentry CLI
npm run check # typecheck, prettier, prose gate, tests
npm run format # prettier --write
npm run workflows-check # no fork-reachable workflow job on a self-hosted runner (python3 with PyYAML)scripts/package.sh <version> <out-dir> builds the downloadable tarball and
node scripts/package-smoke.mjs <tarball> unpacks it and starts the server.
CI runs both on every pull request.
The server is dist/index.js, from a source build or from an unpacked
agentry-mcp-<version>.tar.gz.
Claude Code
claude mcp add agentry -- node /path/to/agentry-mcp/dist/index.jsCodex
codex mcp add agentry -- node /path/to/agentry-mcp/dist/index.jsEither host can pass AGENTRY_BIN when the CLI is not on its PATH:
claude mcp add agentry -e AGENTRY_BIN=/path/to/agentry -- node /path/to/agentry-mcp/dist/index.js
codex mcp add agentry --env AGENTRY_BIN=/path/to/agentry -- node /path/to/agentry-mcp/dist/index.jsSKILL.md is a skill for the host (copy it to
~/.claude/skills/agentry/SKILL.md or ~/.codex/skills/agentry/SKILL.md)
that covers installation, registration, consent, runs, sessions, Knowledge,
Writing Voice and authoring.
Read tools run one CLI command with an argv built from typed arguments, never
a shell string. The result is the CLI's JSON in an envelope with exitClass
and the CLI's last stderr lines as log.
Tool | Runs | Returns |
|
| results, facets, total |
|
| the agent, its latest published version, the capability contract, whether it carries an attestation (signed or unsigned) |
|
| the digest match and the attestation's verdict |
|
| signed-in account and tier |
|
| embedded package refs and archive digests |
|
| local packs or an organization's shared packs |
|
| local and account Voice metadata and review |
|
| machine readiness: policy, provider key name, docker, images, exec catalog |
|
| the schedules on this computer: repeat, next run, output folder, paused |
|
| the OAuth connections kept for QuickAgent versions' MCP servers, never a token |
|
| the model sign-ins local runs can spend, never a token |
|
| the report design a run's PDFs would take, and what chose it |
|
| the saved destinations (name, kind, host, on my network) and the QuickAgents each is a default for, never a secret |
Writing and running tools take two calls. The first, without confirm, runs
the CLI's plan mode, writes nothing and returns what consent would cover plus
a digest: an HMAC-SHA-256, under a key only the server process holds, over
exactly those facts. The second carries that digest. The server plans again,
refuses if anything changed, and only then runs the command. --yes,
--allow-unsigned and --allow-unscanned reach the CLI from no other path
(CI checks this). An unsigned release needs acceptUnsigned: true on the
confirm, an unscanned one acceptUnscanned: true; other refusals stop the
confirm. When the host supports MCP elicitation, the server also asks the
person before the write.
Tool | Runs | Returns |
|
| the preview with a |
|
| the preview with a |
|
| every install record, with |
Tool | Runs | Returns |
|
| the policy as configured — provider, model, the key's variable name — and whether the images are ready |
|
| the run plan with a |
|
| a preview of the run's deliverables, the folder and the destinations with a |
|
| the rules and scan findings as data, and whether publish would pass |
A run's preview is the CLI's compiled run plan with the attestation verdict
and every refusal a run would meet. A run stops at timeoutSeconds, or at the
runner policy's own budget when the call names none: the CLI ends it, the
server sends SIGINT 30 s later if the process is still there, and kills it
60 s after that. Progress streams as MCP progress notifications when the
host asks for them.
A run's deliverables, the files it was for, come back after the envelope.
Text ones (Markdown, plain text, CSV, JSON, YAML, XML, HTML) are embedded
resources, up to 256 KiB each and 1 MiB in all. Every other one is a resource
link: to the copy the run delivered with deliverTo (or the CLI's
deliver.folder setting) when that copy still matches, else to the file in the
run folder. Each file is read through no link and must match the size and
SHA-256 the runner listed before it is inlined or linked; one that does not is
withheld. A link names the file as it was when the server checked it; the
envelope carries each file's SHA-256 for a reader that opens it later. The
envelope's deliverables says what came of each file, and why
one was linked rather than inlined, or withheld. deliverTo needs a CLI with
run --deliver-to.
The run preview's delivery says where the run sends its result: the folder,
and the saved destinations, the call's destinations or else the default set
the person saved for that QuickAgent (noDestination sends to none). The
default set is in the digest, so one changed between the preview and the
confirm refuses the confirm. reportTheme picks a built-in theme for the
run's PDFs. An input source's token and a target host's password, passphrase
or sudo password are passed as the name of an environment variable
(intakeTokens, hostPasswords, hostPassphrases, hostSudoPasswords) and
a host key as a file path (hostKeys); otherwise the CLI uses what the
person saved in the system keychain. The preview's signIns and the
question put to the person name each variable and the source or host it
signs in to, since its value goes there. A session's preview names its
destinations too: a session delivers at its end. The destination list shows a
destination's host, never its path or secret, so one saved again under the
same name and host reads as the same destination. agentry_deliver sends a run already
made to a folder or to saved destinations again, behind the same two calls.
Interactive sessions launch agentry run --mode interactive --session-protocol --output-format json, with JSON-line commands on stdin
and an event pipe on descriptor 3. One session runs at a time. Windows uses
the terminal CLI because the pipe protocol is unavailable there.
Tool | Runs | Returns |
|
| the plan with a |
| a JSON send command to the open chat session | the agent's reply as the events receipt recorded it, the tools it called, the usage |
| a consented JSON add command to the open chat session | staged file submission; collect its notice or refusal with send |
| a JSON end command to the open chat session, then the CLI's teardown | why the session ended, the envelope's status and result, the transcript, the receipts directory |
Persistent agents run in the background once started and keep their
conversation from one start to the next: the Assistant and the Coding agent.
Main runs only in Agentry Desktop. A start that would give the agent something
the person has not agreed to on this computer, and every roster switch, are
two calls like an install: the preview lists each consent sentence with a
digest, and the confirm re-reads them and refuses any change. A send is one
agentry agent attach --json process that leaves the agent running; another
chat's turn in flight makes it busy. Windows uses agentry agent chat in a
terminal because the pipe protocol is unavailable there. The roster names the
agent's skills, stored secrets (by name, never a value), git host accounts,
heartbeat, the Assistant's meetings switch (CLI v0.6.195 or later: with
the heartbeat on, it lets the Assistant ask Agentry Desktop to record the
meetings on the person's calendar that they asked it to record, each armed
window shown and cancelled in the desktop), calendar feeds (calendar:<name>)
and offered servers, and a grant
switches any of them. The
Assistant's mail servers (Google Workspace, server:gog; Microsoft 365 and Outlook.com, server:ms365; Fastmail, server:url-api-fastmail-com-mcp) are on its roster only
while their mail provider is enabled. Adding a skill, storing a secret, giving
an account, choosing the Assistant's mail providers (agentry agent configure assistant --mail-provider), each provider's sign-in (--google-client, --google-sign-in, --microsoft-client, --microsoft-sign-in, and Fastmail's token, --fastmail-token and --no-fastmail), the Assistant's calendar feeds
(agentry agent configure assistant --calendar-feed <name> and
--no-calendar-feed <name>, which take a calendar's secret iCal address;
needs CLI v0.6.205 or later), exporting the memory,
removing a task and the Assistant's three resets (agentry agent reset assistant --history, --keep-credentials, and plain reset) stay in a
terminal or the desktop: each takes a file, a value or a sign-in that belongs on
the person's own screen, or removes what the person set up.
Tool | Runs | Returns |
|
| each agent and whether it is running, stopped, disabled or desktop only |
|
| its state, segment, roster, share folder, usage and the transcript's end |
|
| the running status, or what needs agreement with a |
|
| the stop's status and the segment's result file |
|
| the agent's reply, the tools it called and the usage, or busy |
|
| the entry and its sentence with a |
|
| each task's schedule, state, next and last fire, or the changed tasks |
|
| what it does and spends with a |
Authoring tools use operation previews, since the CLI offers no compiled plan mode for them. The preview names the command, input fingerprints, output, web choice, budgets, policy digest, embedded-package digests and current Knowledge and Voice metadata; the confirm re-reads those facts and refuses changes. These runs use the person's keys and can incur model, AI Review and search charges.
Tool | Runs | Returns |
|
| draft/package and receipts |
|
| Examiner report and expected or undetermined gate outcome |
|
| Creator build report, the sources it fetched, receipts |
|
| Voice Writer build report, each page's outcome, receipts |
A knowledge build takes git repositories (repos, https, with @ref for a
branch, tag or commit) and file addresses (urls) beside its files, and a
voice takes pages of the person's writing (urls). The CLI fetches each one
before the run, through a proxy to its host alone, and the preview lists every
address with the host it reaches. A voice's pages are read by AI Review with
the person's own TypeSafe key before the Voice Writer reads them, so a voice
with urls needs that key. A private repository's access token is the one
saved for its host in the system keychain; the server never takes or passes a
token (--source-token stays in a terminal). Both need a CLI that has them:
the server checks at start and asks for an update otherwise.
Not exposed: signing in (agentry login, agentry connect, agentry model-signins add), publishing (agentry publish), shipping a Knowledge
pack with a QuickAgent (agentry knowledge ship, agentry draft --ship, and
the per-pack confirmation agentry publish asks), forking and yanking,
adding, editing, pausing or removing schedules, saving or removing
destinations and default sets, importing or resetting the report design,
Knowledge import/upload/download/export/delete, Voice
set/attach/delete and account upload/download, enabling, configuring and
resetting a persistent agent (agentry agent enable, configure, reset;
the Assistant's mail providers and its three resets among them),
agentry files ensure,
Unsafe Mode and vulnerable-server lifts, and a build's source tokens. Those
stay in a terminal.
Shipping a Knowledge pack publishes its contents: everyone who can download
the release can read the pack, and it stays in that version. The person
confirms each pack in a terminal, so agentry_draft takes no ship argument
and no tool passes --ship, --namespace or --yes. A draft reads the packs
named in knowledge and ships none of them.
The server has no credential store. Tools take key names and never return their values.
Path | Contents |
| the server: CLI seam, consent, runs, sessions, tools |
| tests against a fake |
| packaging, the prose gate and the workflow fork-guard check |
| a separate registry-API server with its own build, see its README |
MIT, see LICENSE. Security reports: SECURITY.md.
This server cannot be deployed
Discover, search, invoke, and rate A2A (Agent-to-Agent) protocol agents.
Agent-native catalogue of Baseframe Labs dev tools and MCP servers.
Scoped agent execution. Server-side credentials, policy, budgets and verifiable receipts.
Machine-native capabilities with explicit contracts and machine-readable commerce.
