Agent Deck MCP server
Commit Nov 13, 2026Provides a unified source of truth for managing playbooks, tools, and credentials across different coding agents and workspaces.
Also known as not-so-fat/agent-deck
- Stars
- 6
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is Agent Deck MCP?
Agent Deck provides a unified source of truth for managing playbooks, tools, and credentials across different coding agents and workspaces.
Summary generated from the project's README
About Agent Deck MCP server
Agent Deck provides a centralized management system for maintaining consistent workflows across different coding agents and workspaces. It acts as a governed source of truth where developers can bundle MCP services, credentials, and playbooks into specific decks. This allows a single set of instructions or tools to be used by various clients like Claude Code, Cursor, Codex, or Muse without needing to reconfigure each agent individually.
The system operates locally on macOS, utilizing the macOS Keychain to securely store API keys, OAuth tokens, and client secrets. Users interact with the service through a dashboard and a command-line interface, managing their environment via the agent-deck CLI. By switching decks, an agent can instantly adopt new procedures, such as specific PR rules or ticketing workflows, ensuring that the context remains accurate regardless of the specific repository or agent being used.
What you can do with it
- 1Standardize agent workflowsEnsure that different coding agents follow the exact same procedures for tasks like opening pull requests or writing tickets.
- 2Centralize tool credentialsManage API keys and OAuth connections for services like Slack, Notion, or Linear in one place.
- 3Automate playbook improvementsTurn manual corrections of agent mistakes into permanent, reviewable updates for your procedures.
- 4Delegate tasks between agentsLaunch and manage a separate agent session from within your current bound session to execute specific runs.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablenot-so-fat/agent-deck is public and reachablegithub.com/not-so-fat/agent-deck ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/not-so-fat/agent-deck ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubAgent Deck
Keep the way you work consistent across coding agents and workspaces. Agent Deck gives every agent the right playbooks, tools, and credentials from one governed source of truth.
Watch the 100-second overview — one playbook across agents and workspaces.
Why · Quick Start · How learning works · Delegate · Everyday commands · Docs
Bringing a friend (or starting cold)? Follow the one-page friend path: cold machine → first deck switch → first Dealer issue.
Why
You teach one coding agent how you work: how to open a PR, write a ticket, check a release, or use your knowledge base. Then you switch to another agent and teach it all again.
- Consistency across agents. The same playbook can guide Claude Code, Codex, Cursor, or another MCP client. You maintain one procedure instead of separate copies for every agent.
- Consistency across workspaces. Reusable PR rules, ticketing procedures, UI principles, and knowledge-base workflows live in one collection. Attach them to the decks that need them instead of duplicating them across repositories.
- One governed source of truth. A deck bundles the MCP services, credentials, and playbooks for one context. The agent sees only that deck. Switch decks instead of rewiring agents; improve a playbook once and reuse the lesson everywhere.
One MCP endpoint, registered once.
The execution half is agent-dealer: queue tasks against a deck, approve the plan before anything runs, execute headless under budget caps, review results, and gate every outbound send — Dealer runs consume deck playbooks and file patch proposals back.
Quick Start
macOS required. API key secrets, OAuth client secrets, and OAuth tokens are stored in macOS Keychain. Linux and Windows are not supported for production use yet.
Requirements: Node.js 20+ · npm · Dashboard via agent-deck start / agent-deck open (listens on 127.0.0.1:1111) · Agent Deck MCP http://127.0.0.1:1110/mcp
1. Install and launch (managed install — auto-updates, keeps existing ~/.agent-deck data):
npx @agent-deck/cli@latest install
export PATH="$HOME/.local/bin:$PATH"
agent-deck start --daemon
2. Register Agent Deck in your agent (once per machine; <client> is codex, cursor, claude, or muse):
agent-deck setup --client <client>
Per-client details, restart and verify steps, and what setup installs: Agent harness.
3. Create a deck in the dashboard (My Decks → create a deck → drag cards from My Collection), or ask the agent in chat to create one.
4. Register playbooks (agent-first). Describe the procedure in chat — e.g. “Add a release checklist playbook with trigger ‘ship to npm’.” Let the agent register it and attach it to your deck.
5. Add external MCP servers and API keys (Linear, Notion, Slack, …) in the dashboard — OAuth in the browser, API keys pasted once into Keychain — then drag the cards onto your deck.
6. Pick a deck each session. Tell the agent which deck — “use the dev deck”, or mid-session “switch to my personal deck” — and approve the switch as This session only or This workspace by default. Or run agent-deck use <deck> in a repo so the deck binds on session open without naming it.
Same decks on another machine: keep ~/.agent-deck/ in a private Git repository you own, push and pull it yourself, then run agent-deck reindex — see Store format.
How learning works
When you correct a playbook-driven result, Agent Deck turns the lesson into a reviewable patch proposal so future sessions start from what you taught it. Corrections become proposals you review in the dashboard (Playbook patches); accepted changes update the deck. Every run makes the next one better.
If you use per-repo use stubs and playbook triggers changed, refresh with agent-deck use --refresh.
Delegate to another agent
Agents delegate through Agent Deck MCP: from a bound session, start_run launches a signed-in client on the Agent Deck host in the session's launch workspace and deck, get_run pages its events to a terminal state, and start_run with resumeSessionId or cancel_run continues or stops it. The agent-deck-run skill is the protocol; MCP_RUN_TOOLS.md is the tool contract.
On the host itself, an operator can also start a run from a terminal for installation checks, diagnostics, or recovery:
agent-deck run mydeck --client claude --cwd /path/to/repo --prompt-file ./brief.md --tools readonly
Per-client flags, resume, and trust behavior, and which path to use: DELEGATION.md.
Install as an agent plugin
The repo root is one plugin: one skills/ folder (agent-deck-session, agent-deck-playbooks, agent-deck-setup, agent-deck-run), described by a manifest per client. The Codex and Claude manifests declare no MCP server (skills and guidance only); the Cursor manifest points at its own .cursor-plugin/.mcp.json. Prerequisites for delegation: agent-deck >= 2.1.0 and the daemon running (see Quick Start), and the client CLI you delegate to, installed and signed in. The agent-deck-setup skill checks these and tells you what is missing.
| Client | Install | Manifest |
|---|---|---|
| Claude Code | /plugin marketplace add not-so-fat/agent-deck, then /plugin install agent-deck@agent-deck |
.claude-plugin/plugin.json + marketplace.json |
| Cursor | add not-so-fat/agent-deck as a plugin marketplace and install agent-deck |
.cursor-plugin/plugin.json + marketplace.json |
| Codex | codex plugin marketplace add not-so-fat/agent-deck, then codex plugin add agent-deck@agent-deck |
.codex-plugin/plugin.json (Codex reads the marketplace from .claude-plugin/marketplace.json) |
| muse | agent-deck setup --client muse (installs the four skills into ~/.config/muse/skills/), or muse plugins install <clone path> (muse imports .claude-plugin/plugin.json) |
.claude-plugin/plugin.json |
Skills are never copied by hand: the muse copies come from root skills/ via scripts/copy-muse-skills.mjs at build time and agent-deck setup --client muse at install time.
Cursor: setup and a test task
- Install agent-deck and start it (Quick Start above):
npx @agent-deck/cli@latest install,agent-deck start --daemon, thenagent-deck doctor. - Install the agent-deck plugin from the Cursor Marketplace (or, for local testing, copy this repo to
~/.cursor/plugins/local/agent-deckand run Developer: Reload Window). The plugin adds the four skills and theagent-deckMCP server (agent-deck mcp-launch, from.cursor-plugin/.mcp.json); it needs theagent-deckCLI onPATHand stores no secrets. - Create a deck in the dashboard (
agent-deck open), then bind a project folder:agent-deck use <deck> --client cursor, and reload Cursor. - Test task: open that folder and ask the agent: "Use the agent-deck-setup skill to check my Agent Deck setup and tell me what is missing." Expected: it runs read-only checks (
agent-deck --version,agent-deck status,agent-deck deck list) and reports the result. Then try delegation: "Use agent-deck-run to have a read-only claude session on deck list the files in this folder, and report its answer." Expected: it callsstart_runwithclient: "claude"andtools: "readonly", pollsget_rununtil the run is terminal, and reports the session's answer with therunId,sessionId, tool profile, and terminal state.
Everyday commands
agent-deck start --daemon
agent-deck open # re-open dashboard with a fresh auth cookie
agent-deck use <deck> # bind this folder to a deck
agent-deck export all -o backup.agent-deck.json
agent-deck credential list
agent-deck exec --connections cred_id -- <command>
agent-deck upgrade
agent-deck stop
Port conflicts: agent-deck status · agent-deck start --force. Full environment reference: Setup.
Documentation
Index: docs/README.md · Security: SECURITY.md
| Guide | Description |
|---|---|
| Friend path | Cold machine → first deck switch → first Dealer issue |
| Direction | Cross-product direction — agent_deck + agent-dealer |
| Setup | Ports, env vars, secrets, troubleshooting |
| MVP | Source of truth — decks, vault, playbooks, MCP tools |
| Agent harness | What setup installs |
| Delegation | agent-deck run per-client reference |
| Agent run API | Same-host HTTP start, observe, cancel, and resume |
| Playbooks vs Cursor skills | Deck playbooks vs Cursor skills |
| Export / import | Portable layout bundles |
| Store format | File-backed store layout, sync, reindex |
| Deck display | Terminal status line |
| Codex / Claude plugin | Marketplace packaging (HOL / Codex / Claude Code) |
| Architecture | SQLite, Keychain, components |
| Development | Contributors |
| Publishing | npm release |
License
MIT — see LICENSE.
Agent Deck MCP questions
Which operating systems are supported?
Currently, macOS is required for production use. Linux and Windows are not yet supported for production.
How can I keep my agent configurations consistent across different machines?
You can keep your ~/.agent-deck/ directory in a private Git repository and run agent-deck reindex after pushing and pulling.
Can I use Agent Deck with Cursor or Claude Code?
Yes, Agent Deck is compatible with Claude Code, Cursor, Codex, and Muse.
