Connect an AI agent

Give Claude, Cursor, Codex, ChatGPT or your own agent access to PlaybookOps over MCP.

PlaybookOps runs a remote Model Context Protocol server. Point your client at this address and send an API key:

https://mcp.playbookops.ai

The tools are the API's actions, like list_projects, search_knowledge, create_item and update_document, with the same inputs and answers as the API reference. An agent only sees the tools its key's scopes allow, so with a read-only key it has no way to change anything.

Make a key just for the agent

Make a key named after the agent, with the least access that works. Every change the agent makes is recorded against that key, and you can revoke it at any time.

Set up your client

claude mcp add --transport http playbookops https://mcp.playbookops.ai \
  --header "Authorization: Bearer $PLAYBOOKOPS_API_KEY"

Run /mcp inside Claude Code to check that it's connected.

Model APIs that connect to MCP servers themselves, like Anthropic's MCP connector and OpenAI's remote MCP tool, need the same two things: the address https://mcp.playbookops.ai and the key as a Bearer token.

Try it out

Once connected, ask your agent something like:

  • "What's due this week on my PlaybookOps tasks?"
  • "Search our playbooks for how we handle refunds over $500, and link the document."
  • "Who knows the most about payroll?"
  • "Add an item to the Launch board for calling the venue, due Friday, assigned to me."

What the agent gets back

  • Every tool returns structured JSON (structuredContent) that matches its output schema, plus the same JSON as text.
  • A failed call comes back with isError: true and a plain sentence, like "This key can't do that. It needs the projects:write scope." The agent can read it and adjust.
  • Tools that change things are marked as such, and delete_item and delete_task are also marked as destructive, so clients that ask before running them will ask.
  • Calls count toward the same rate limits and credits as the REST API.

Retrying changes

Every tool that changes something takes an optional idempotency_key argument. Retry with the same key and the agent gets the first answer back instead of making the change twice, just like the REST API's Idempotency-Key header. Ask your agent to send one with every change. See retries and idempotency.

Resources

Playbooks and documents are also MCP resources, for clients that let you attach context directly (like adding a document to a chat) instead of having the agent call tools. They need knowledge:read.

AddressWhat you get
playbookops://playbooks/{playbook_id}The playbook as a Markdown outline: its folders, and each document with its own resource address
playbookops://documents/{document_id}The document's full Markdown

Listing resources returns your 15 newest playbooks. Any playbook or document you can open in the app can be read by its address.

https://developers.playbookops.ai/mcp is the same server, if you'd rather use one address for everything.