MCP Integration

This guide explains how to use AgentPlaybooks with the Model Context Protocol (MCP).

What is MCP?

The Model Context Protocol (MCP) is an open standard developed by Anthropic that enables AI assistants to securely connect to external data sources and tools.

AgentPlaybooks provides a direct MCP endpoint for each playbook and a user-level control plane that can create a playbook and immediately apply it.

The third row is for agents that write code instead of calling tools one at a time — some of them cannot call MCP tools from inside their scripts at all. llms.txt is one fetch that explains authentication and the one-POST calling convention (POST /api/mcp/YOUR_GUID/tools/TOOL_NAME with JSON arguments), with a one-shot example per tool. The dashboard's Integrations tab shows all three.

OAuth 2.1 with PKCE is the default for interactive clients. The endpoint publishes protected-resource metadata, discovers the AgentPlaybooks authorization server, and shows a consent screen before account access is granted. User and playbook API keys remain supported for headless automation and clients without OAuth.

Both scopes project the same canonical playbook operations. The user control plane is the endpoint published to registries such as Glama because it supports the full account-to-playbook lifecycle in one connection.

Quick Start

1. Get Your MCP Endpoint

After creating and publishing a playbook, your MCP endpoint is:

https://apbks.com/api/mcp/YOUR_GUID

2. Configure Your MCP Client

One-click install (Cursor, VS Code)

Both editors accept an install link that opens their own dialog with the server already filled in. The endpoint signs you in with your AgentPlaybooks account (OAuth), so the link carries only the URL — no key is written into the editor's config.

Your whole account — every playbook you own or have been given:

• Add AgentPlaybooks to Cursor
• Add AgentPlaybooks to VS Code

One playbook — open the playbook's Integrations tab and use Add to Cursor or Add to VS Code there; those links carry that playbook's own URL.

To build a link yourself, the formats are:

cursor://anysphere.cursor-deeplink/mcp/install?name=<entry>&config=<base64 of {"type":"http","url":"<endpoint>"}>
vscode:mcp/install?<URL-encoded {"name":"<entry>","type":"http","url":"<endpoint>"}>

src/lib/mcp-install-links.ts builds both, with tests. If the editor's sign-in does not open, use the manual configuration below with an API key instead.

Cursor IDE

Add to your project's .cursor/mcp.json or global ~/.cursor/mcp.json:

{
  "mcpServers": {
    "apb-my-playbook": {
      "url": "https://apbks.com/api/mcp/YOUR_GUID"
    }
  }
}

For private playbooks, include your API key in the headers:

{
  "mcpServers": {
    "apb-my-playbook": {
      "url": "https://apbks.com/api/mcp/YOUR_GUID",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

After saving, restart Cursor or reload the window. Your playbook's tools and resources will appear in the MCP tools panel.

Tip: You can find the ready-to-copy config in the Integrations tab of your playbook's dashboard. The server name uses the short apb- prefix to stay within Cursor's 60-character combined name limit.

Claude (web, Desktop, Cowork, mobile)

Add the endpoint as a custom connector — no API key needed, because the endpoint signs you in with your AgentPlaybooks account over OAuth:

• Open Customize → Connectors and

choose Add custom connector.

• Paste https://agentplaybooks.ai/api/mcp/YOUR_GUID, or

https://agentplaybooks.ai/api/mcp/manage for every playbook in your account.

• Select Add, then Connect, and sign in.

Or install the AgentPlaybooks plugin, which adds the account connector and a skill for using it. AgentPlaybooks in Claude covers both routes, Team and Enterprise plans, and self-hosted servers.

Not claude_desktop_config.json. That file describes local stdio servers

only — a command and its arguments. A url and headers written there are

ignored, and nothing reports an error: the server never appears. Earlier

versions of this page recommended it; it could not have worked.

Claude Code (CLI)

claude mcp add --transport http apb-my-playbook https://agentplaybooks.ai/api/mcp/YOUR_GUID

Then run /mcp and choose Authenticate to sign in.

Verify the connection:

claude mcp list

Custom MCP Client

import { Client } from "@modelcontextprotocol/sdk/client";

const client = new Client({
  name: "my-app",
  version: "1.0.0"
});

// Connect to playbook
await client.connect({
  transport: "http",
  url: "https://apbks.com/api/mcp/YOUR_GUID"
});

// List available tools
const tools = await client.listTools();

// Read resources
const memory = await client.readResource({
  uri: "playbook://YOUR_GUID/memory"
});

Agent Usage Pattern (Recommended)

To match AgentPlaybooks goals (portable, up-to-date, self-improving agents), run MCP in this loop:

• Initialize and inspect once

- initialize - tools/list - resources/list

• Read the guide first

- resources/read for playbook://YOUR_GUID/guide

• Fetch only what you need

- read_memory for known keys - search_memory for discovery - read_canvas / get_canvas_toc for longer docs and plans

• Execute work with tools

- Use built-in playbook tools and skill tools

• Write back outcomes

- write_memory for compact facts/state - write_canvas / patch_canvas_section for detailed runbooks, postmortems, or long plans

This keeps context fresh, avoids token waste, and prevents repeating the same mistakes across sessions.

MCP Server Manifest

When you access the MCP endpoint, it returns a server manifest:

{
  "protocolVersion": "2024-11-05",
  "serverInfo": {
    "name": "My AI Assistant",
    "version": "1.0.0",
    "description": "A helpful coding assistant"
  },
  "capabilities": {
    "tools": {},
    "resources": {}
  },
  "tools": [
    {
      "name": "code_review",
      "description": "Review code for bugs and improvements",
      "inputSchema": {
        "type": "object",
        "properties": {
          "code": { "type": "string" },
          "language": { "type": "string" }
        }
      }
    }
  ],
  "resources": [
    {
      "uri": "playbook://abc123/personas",
      "name": "Personas",
      "description": "AI personalities and system prompts",
      "mimeType": "application/json"
    },
    {
      "uri": "playbook://abc123/memory",
      "name": "Memory",
      "description": "Persistent key-value memory storage",
      "mimeType": "application/json"
    }
  ],
  "_playbook": {
    "guid": "abc123",
    "personas": [
      {
        "name": "Coder",
        "systemPrompt": "You are a helpful coding assistant..."
      }
    ]
  }
}

Available Tools

The MCP server exposes built-in tools for interacting with the playbook. Skills are not exposed as separate tools — they are instructions and knowledge that agents read via the list_skills, get_skill tools or the Skills resource.

Built-in Tool Categories

Canvas documents are isolated by workflow run. Pass run_id to document-level canvas tools; create one first with create_run. The control plane additionally requires playbook_id, while the direct endpoint gets the playbook from its URL.

Toolsets: advertise less, keep everything callable

A connected client pays tokens for every advertised tool on every call. The toolset query parameter narrows what tools/list returns:

https://agentplaybooks.ai/api/mcp/YOUR_GUID?toolset=runtime

One connection is enough. On an unpinned connection the agent discovers what it needs with find_tools(query) — keyword search over the full catalog, built-in and federated alike, returning name, description, and input schema — and then calls the result directly, whether or not it was advertised. Add the same playbook twice only when you want differently scoped connections: a pinned toolset is a deliberate boundary, and find_tools on a pinned connection searches only within it. An unknown toolset name is a 400, never a silent fallback to full.

Available Resources

Each playbook exposes these resources:

JSON-RPC Methods

The MCP endpoint supports standard JSON-RPC 2.0:

Initialize

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}

List Tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

List Resources

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/list"
}

Read Resource

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/read",
  "params": {
    "uri": "playbook://abc123/memory"
  }
}

Adding MCP Servers to Your Playbook

You can define custom MCP server configurations within your playbook:

• Go to the MCP Servers tab in the Playbook Editor
• Click "Add MCP Server"
• Define tools and resources

These will be merged into your playbook's MCP manifest.

Example MCP Server Definition

{
  "name": "file_tools",
  "tools": [
    {
      "name": "read_file",
      "description": "Read contents of a file",
      "inputSchema": {
        "type": "object",
        "properties": {
          "path": { "type": "string" }
        },
        "required": ["path"]
      }
    }
  ],
  "resources": [
    {
      "uri": "file:///workspace",
      "name": "Workspace",
      "mimeType": "text/plain"
    }
  ]
}

Secrets Vault

AgentPlaybooks includes a built-in secrets vault for encrypted credential storage. Secrets are encrypted with AES-256-GCM using per-user derived keys.

Security Design

By default, agents use the use_secret tool as a server-side proxy instead of reading secret values directly. Owners can separately opt a secret into API-key reveal access.

For incremental model output, browsers and HTTP clients can bypass MCP using POST /api/playbooks/:guid/secrets/proxy with response_mode: "stream". The provider key is still injected server-side. MCP supports SSE transport, but APB's current secret tools buffer the upstream response into a final tool result; direct HTTP streaming avoids that buffering.

• Agent calls use_secret with a secret name and target URL
• Server decrypts the secret internally
• Server makes the HTTP request with the secret injected as a header
• Only the HTTP response is returned to the agent

This ensures credentials never appear in agent context, logs, or conversation history.

Available MCP Tools

Example: Using a Secret

{
  "method": "tools/call",
  "params": {
    "name": "use_secret",
    "arguments": {
      "secret_name": "OPENAI_API_KEY",
      "url": "https://api.openai.com/v1/models",
      "method": "GET",
      "header_name": "Authorization",
      "header_prefix": "Bearer "
    }
  }
}

The agent receives only the API response — the secret value stays on the server.

Example: Storing a Secret

{
  "method": "tools/call",
  "params": {
    "name": "store_secret",
    "arguments": {
      "name": "OPENAI_API_KEY",
      "value": "sk-...",
      "description": "OpenAI API key for GPT-4",
      "category": "api_key"
    }
  }
}

Authentication

Public playbooks require no authentication for read access. Anyone can connect to the MCP endpoint and use the playbook's tools and resources.

Private playbooks require a Playbook API Key. Generate one from the Integrations tab in your playbook's dashboard.

Include the key in the Authorization header:

Authorization: Bearer apb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Write-back operations (writing memory, canvas, etc.) always require an API key, even for public playbooks. The key must have the appropriate permissions (e.g. memory:write).

On a private playbook, any active key of that playbook reaches the MCP endpoint. Each operation then checks its own permission:

• Memory reads need memory:read, skill reads skills:read, canvas and run reads canvas:read, and the connected servers list playbooks:read.
• A key that holds memory:read can read everything, as it always could.
• A write permission includes reading the same area: memory:write also reads memory, skills:write also reads skills (likewise personas, canvas and playbooks). It does not read anything else.
• Secrets are the exception: secrets:write stores, rotates and deletes credentials but does not use them; using a secret through the proxy needs secrets:read.
• A key with no read or write of an area, for example one that only uses secrets, reaches the endpoint but reads nothing.

The read-only manifest (GET /api/mcp/:guid) and llms.txt still need a key with memory:read.

API keys come in four roles:

• Viewer — Read-only access
• Proposer — Read access; memory and skill changes wait for review
• Coworker — Read and write access
• Admin — Full access to modify playbook structure

Proposals

A key with memory:propose or skills:propose (the Proposer role) may suggest changes it is not allowed to make. write_memory, create_skill and update_skill (and PUT /api/playbooks/:guid/memory/:key, which answers 202) then save the change as a proposal instead of applying it:

{ "status": "pending_review", "kind": "memory", "proposal_id": "…", "target": "lesson/check-the-register" }

A proposal changes nothing until it is approved. It is not returned by memory reads, search, context or history, nor listed as a skill version. The owner and editors see pending proposals at the top of the Memory and Skills tabs and approve or reject them there. Approving applies the proposal as an ordinary write, so the previous content stays in the history. Keys can review too: a key with memory:write reviews memory proposals, and one with skills:write reviews skill proposals:

GET  /api/playbooks/:guid/proposals?kind=memory|skill
POST /api/playbooks/:guid/proposals/:id   {"kind": "memory", "decision": "approve" | "reject"}

A propose permission never grants reading. Give a proposer memory:read / skills:read as well when it needs to see what is already there; the Proposer role does.

Best Practices

• Keep tools focused - Each tool should do one thing well
• Write clear descriptions - MCP clients use these to understand capabilities
• Define schemas carefully - Well-defined input schemas help AI use tools correctly
• Use resources for data - Resources are better than tools for read-only data access
• Start with the guide resource - Read playbook://GUID/guide before complex tasks
• Fetch minimally - Read targeted resources/keys first, not full dumps by default
• Close the loop - Save discovered constraints/workarounds to memory or canvas
• Test with Claude Desktop or Cursor - Verify your MCP configuration works before deploying

Troubleshooting

Connection Issues

"Playbook not found" (404)

• Ensure the playbook is set to Public, or include a valid API key for private playbooks
• Verify the GUID in the URL is correct (check the Integrations tab)

Authentication failures (401/403)

• Verify your API key starts with apb_live_
• Ensure the key has not been revoked
• Check the Authorization: Bearer header format

Cursor-Specific Issues

MCP server not appearing

• Ensure the JSON in .cursor/mcp.json is valid (no trailing commas)
• Restart Cursor after saving configuration changes
• Check Cursor's MCP logs for connection errors

"Naming issues" warning — Combined server and tool name length exceeds 60 characters

• Cursor limits server_name + tool_name to 60 characters total
• Use the short apb- prefix for your server name (e.g. apb-my-playbook instead of agentplaybooks-my-playbook)
• The ready-to-copy configs in the Integrations tab already use the short prefix

Tools not loading

• Verify the playbook has data (skills, memory, etc.) — use list_skills or get_memory_context to confirm
• Test the endpoint directly: curl -s https://apbks.com/api/mcp/YOUR_GUID | head -c 200

Claude Issues

Nothing appears after editing claude_desktop_config.json

• That file cannot hold a remote server. Add the endpoint as a custom connector

or install the plugin instead — see AgentPlaybooks in Claude.

The connector shows Connect or Reconnect, not Connected

• The sign-in did not finish. Select it again and complete the AgentPlaybooks

sign-in in the window that opens.

A tool call is refused

• The refusal names the missing permission or the reason. A playbook shared with

you as a viewer, for example, cannot be written.

---

Clawdbot Integration

Clawdbot is a popular open-source, self-hosted AI assistant that connects messaging platforms (WhatsApp, Telegram, Discord) with LLM APIs. It has full MCP support.

Connecting AgentPlaybooks to Clawdbot

Add to Clawdbot's config.yaml:

mcp_servers:
  - name: agent-playbook
    transport: http
    url: https://apbks.com/api/mcp/YOUR_GUID
    description: My custom AI playbook with skills and memory

messaging:
  whatsapp:
    enabled: true
    phone_number: "+1234567890"
  telegram:
    enabled: true
    bot_token: "your_bot_token"

With Authentication (for Memory Write-back)

mcp_servers:
  - name: agent-playbook
    transport: http
    url: https://apbks.com/api/mcp/YOUR_GUID
    auth:
      type: bearer
      token: apb_live_xxx
    write_enabled: true

Benefits of Clawdbot + AgentPlaybooks

See Platform Integrations for Claude Coworker and other integrations.