AgentPlaybooks in Claude
Your playbooks work in every Claude surface — claude.ai on the web, Claude Desktop, Cowork, Claude Code, and the mobile apps — through one MCP endpoint that signs you in with your AgentPlaybooks account. There is no API key to create, copy, or rotate for Claude.
There are three ways in. Pick by what you want Claude to reach:
| Route | Reaches | Works in | Setup |
| The AgentPlaybooks plugin | Every playbook in your account, plus a skill that teaches Claude how to use them | Chat, Cowork, Claude Code | Install once, sign in |
| A custom connector | One playbook, or the whole account | Web, Desktop, Cowork, mobile | Paste a URL, sign in |
| Claude Code only | One playbook or the account, plus local doctor and sync | Claude Code | One command |
The plugin
The plugin bundles four things:
- the AgentPlaybooks connector for the account endpoint
https://agentplaybooks.ai/api/mcp/manage). Every playbook you own or have
been given is reachable through it — including one shared with you after you
install — and each tool call names the playbook it targets;
- a playbooks skill, so Claude knows to look up the right playbook, adopt
- the
/agentplaybooks:doctorand/agentplaybooks:synccommands for
- in Claude Code, a local connection to your own servers: every
From claude.ai or the desktop app.
- Open Customize → Plugins.
- Once the plugin is listed in Anthropic's directory, find AgentPlaybooks
matebenyovszky/agentplaybooks, and add AgentPlaybooks from it.
- Open the plugin's Connectors tab. Adding a plugin does not sign you in to
A plugin added on your account is available in chat, Cowork, and — at the next session start — Claude Code. On Team and Enterprise plans an Owner decides which plugin sources members see, and adds the connector for the organization if members cannot.
From the command line, in Claude Code.
/plugin marketplace add matebenyovszky/agentplaybooks
/plugin install agentplaybooks@agentplaybooksThen run /mcp, choose agentplaybooks-account, and sign in.
The plugin deliberately carries no executables — claude.ai and Cowork refuse a
plugin with a bin/ directory — so its commands run the published CLI through
npx, pinned to the version the plugin was released with. For the CLI's other
commands (connect, pull, push, backups), install it from npm: see
CLI.
A custom connector
Use this to give Claude one specific playbook — so its persona and instructions arrive as the server's own prompt — or when you do not want the plugin.
- Open Customize → Connectors and
- Paste the URL:
https://agentplaybooks.ai/api/mcp/ — copy it from the
playbook's Integrations tab;
- the whole account: https://agentplaybooks.ai/api/mcp/manage.
- Leave the OAuth client ID and secret empty. If the dialog asks how to
- Select Add, then Connect, and sign in to AgentPlaybooks.
A connector added on claude.ai is available in Claude Desktop, Cowork, and the mobile apps too. In a chat, turn it on from + → Connectors.
What the sign-in grants
The connector acts as you. It can read and change what your account can read and change, in every playbook it can reach — no more. Every tool declares whether it only reads: read-only tools — list, search, get — run without asking, and Claude asks before a tool that changes a playbook other people may share, unless you choose Always allow for that tool. Deleting, and calling a connected service, are marked destructive.
Secret values never reach Claude. list_secrets returns names only, and
use_secret makes the request with the value injected on the AgentPlaybooks
server.
Claude Code
Add one playbook or the account with a single command, then sign in from /mcp:
claude mcp add --transport http apb-my-playbook https://agentplaybooks.ai/api/mcp/<guid>claude mcp add --transport http agentplaybooks-account https://agentplaybooks.ai/api/mcp/manageFor a configuration the whole team shares through the repository, use
apb connect or apb connect --account --apply instead — see
CLI. Those write .mcp.json entries that read an API key from an
environment variable, for clients and CI jobs that cannot run a browser sign-in.
Claude Desktop's config file does not work for this
claude_desktop_config.json describes local servers only: a command and
its arguments, launched on your machine. A url and headers written there are
ignored — the server never appears, and nothing reports an error. Earlier
versions of these docs recommended exactly that. Use the plugin or a custom
connector; both work in Claude Desktop.
Self-hosted instances
A self-hosted AgentPlaybooks server works the same way when its Supabase Auth
has the OAuth server enabled: add https:// or
.../api/mcp/ as a custom connector. Claude connects from Anthropic's
infrastructure, not from your machine, so the server has to be reachable from
there — for a server inside a private network, Claude's
MCP tunnels are the
supported route.
In Claude Code, the plugin reaches your own servers without any of that. Its agentplaybooks-servers connection runs on your machine and serves every AgentPlaybooks server you have stored a user API key for with the CLI — no OAuth server needed, and as many servers as you log in to:
npx --yes @agentplaybooks/cli@0.9.0 login --url=https://<your-server>The CLI takes the key from AGENTPLAYBOOKS_API_KEY, or prompts for it without
echoing the value. Enter the key locally; do not paste it into a conversation.
Then reconnect agentplaybooks-servers from /mcp. With more than one
server, list_playbooks marks each playbook with its server, a call that names
a playbook_id goes to the server that has it, and create_playbook asks which
server. Each key goes only to the server it was stored for, over HTTPS (or HTTP
to your own machine), and logout --url= takes it away again. A
server whose certificate comes from a CA outside the operating system's store
needs NODE_EXTRA_CA_CERTS in the env block of ~/.claude/settings.json, and
in the terminal where you run login.
Troubleshooting
- The connector shows Connect or Reconnect, not Connected. The sign-in did
- No tools appear. Open the connector's page and check Tool
- A tool call is refused. The refusal names the missing permission or the
- Claude Code says the server needs authentication. Run
/mcp, choose the