# 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](https://modelcontextprotocol.io) server. Point your client at this address and send an API key:

```text
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](https://developers.playbookops.ai/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 Code**

```bash
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.

**Cursor**

Add this to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project, and set `PLAYBOOKOPS_API_KEY` in your environment:

```json
{
  "mcpServers": {
    "playbookops": {
      "url": "https://mcp.playbookops.ai",
      "headers": { "Authorization": "Bearer ${env:PLAYBOOKOPS_API_KEY}" }
    }
  }
}
```

**Codex**

The Codex CLI, the Codex IDE extension and the ChatGPT desktop app share one config, so you only set this up once. Put your key in your shell profile (like `~/.zshrc`), then add the server:

```bash
export PLAYBOOKOPS_API_KEY="pbo_live_…"
codex mcp add playbookops --url https://mcp.playbookops.ai \
  --bearer-token-env-var PLAYBOOKOPS_API_KEY
```

That adds the server to `~/.codex/config.toml`. You can also write it by hand, there or in a project's `.codex/config.toml`:

```toml
[mcp_servers.playbookops]
url = "https://mcp.playbookops.ai"
bearer_token_env_var = "PLAYBOOKOPS_API_KEY"
# Reads run straight away; Codex asks before anything that makes a change.
default_tools_approval_mode = "writes"
```

Run `codex mcp list` to see it, or `/mcp` inside Codex to check that it's connected. To keep Codex to a few tools, add `enabled_tools = ["search_knowledge", "read_document"]`.

> **Connecting from the desktop app**
> Apps opened from the Dock or Start menu may not see variables from your shell profile. If PlaybookOps shows as unauthorized there, put the key in the config instead with `http_headers = { Authorization = "Bearer pbo_live_…" }`. The key is then stored in that file as plain text, so only do this in `~/.codex/config.toml`, never in a project's config that might be committed.

**Claude Desktop**

Claude Desktop starts servers on your computer, so it connects through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), which needs [Node.js](https://nodejs.org). Open **Settings → Developer → Edit Config** and add:

```json
{
  "mcpServers": {
    "playbookops": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.playbookops.ai", "--header", "Authorization:${PLAYBOOKOPS_AUTH}"],
      "env": { "PLAYBOOKOPS_AUTH": "Bearer pbo_live_…" }
    }
  }
}
```

Replace `pbo_live_…` with your key, and keep `Bearer ` and its space in front of it. You don't set `PLAYBOOKOPS_AUTH` on your computer: Claude Desktop passes the `env` value to `mcp-remote`, which puts it in the `Authorization` header. The key lives in `env` because some systems split arguments that contain spaces, so leave out the space after `Authorization:`.

If the file already has other servers, add `"playbookops"` inside the existing `mcpServers`. Then quit and reopen Claude Desktop, which reads the file only when it starts.

**Python**

With the official [`mcp`](https://pypi.org/project/mcp/) package:

```python
import asyncio
import os

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    headers = {"Authorization": f"Bearer {os.environ['PLAYBOOKOPS_API_KEY']}"}
    async with streamablehttp_client("https://mcp.playbookops.ai", headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])
            result = await session.call_tool("list_projects", {"limit": 5})
            print(result.structuredContent)

asyncio.run(main())
```

**TypeScript**

With the official [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) package:

```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(new URL("https://mcp.playbookops.ai"), {
  requestInit: { headers: { Authorization: `Bearer ${process.env.PLAYBOOKOPS_API_KEY}` } },
});
const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

const { tools } = await client.listTools();
const result = await client.callTool({ name: "list_projects", arguments: { limit: 5 } });
console.log(result.structuredContent);
```

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](https://developers.playbookops.ai/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](https://developers.playbookops.ai/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`.

| Address | What 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.
