Management API & MCP Server

This guide explains how to programmatically manage AgentPlaybooks using the Management API or MCP Server. This enables AI agents to create, update, and delete playbooks on behalf of users.

Overview

AgentPlaybooks provides protocol projections over one shared operation model:

• REST/OpenAPI - Standard resource endpoints plus operation endpoints
• User MCP control plane - Account lifecycle plus every playbook operation
• Direct playbook MCP - The same playbook operations with identity in the URL

Interactive clients can authenticate with OAuth 2.1 + PKCE. User API Keys remain available for automation, CI, and clients that do not support OAuth. Both credentials resolve to the same AgentPlaybooks account and the same authorization boundaries.

---

User API Keys

Unlike Playbook API Keys (which only work for a single playbook), User API Keys represent one user account across the Management API. They can access playbooks owned by that account and playbooks shared with it. This allows AI agents to:

• Create new playbooks (with embedded persona)
• Manage existing playbooks
• Add/update/delete skills and memory
• Manage workflow runs, canvas documents, connected MCP/OpenAPI servers, and secrets (when explicitly permitted)
• Apply a newly created playbook immediately through the same control-plane connection
• List owned and shared playbooks, including current_user_role

For a shared playbook, the User API Key inherits the account's editor boundaries: it may change content but cannot change visibility, manage collaborators or playbook API keys, access secrets, or delete the playbook. Human invitation endpoints themselves require an interactive JWT session and are not exposed through this API.

Architecture Note: AgentPlaybooks uses a 1 Playbook = 1 Persona model. Each playbook has exactly one persona embedded directly in the playbook record. There's no separate personas table.

Creating a User API Key

• Go to your Dashboard Settings
• Click "Create Key"
• Enter an optional name (e.g., "Claude Desktop", "Cursor")
• Select permissions:

- playbooks:read - List and read playbooks - playbooks:write - Create, update, delete playbooks (incl. persona) - personas:read / personas:write - Read or update persona data - skills:read / skills:write - Read or manage skills - memory:read - Read memory - memory:write - Write/delete memory - canvas:read / canvas:write - Read or manage workflow runs and canvas - tools:call - Call protected tools on connected MCP servers - secrets:read / secrets:write - Use or manage encrypted secrets (opt-in) - full - All permissions

• Copy the key immediately (it won't be shown again!)

API Key Format

apb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Via API

POST /api/user/api-keys
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "name": "AI Assistant Key",
  "permissions": ["playbooks:read", "playbooks:write", "skills:write", "memory:read", "memory:write"]
}

Response includes the plain key only once:

{
  "id": "uuid",
  "key_prefix": "apb_live_xxx...",
  "key": "apb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "warning": "Save this key now! It will not be shown again."
}

---

REST API

Base URL

https://apbks.com/api/manage

Authentication

Interactive clients may send the Supabase OAuth access token obtained through the AgentPlaybooks authorization flow:

Authorization: Bearer <oauth_access_token>

For headless automation, include a User API Key instead:

Authorization: Bearer apb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

OpenAPI Specification

Get the full OpenAPI spec:

GET /api/manage/openapi.json

This can be used with:

• ChatGPT Custom Actions
• OpenAPI-compatible tools
• API documentation generators

The specification also contains the generalized operation projection:

POST /api/control/:operation
Authorization: Bearer apb_live_xxx
Content-Type: application/json

Playbook operations require playbook_id in the JSON body. For example:

POST /api/control/create_run

{
  "playbook_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Customer discovery",
  "context": { "customer": "Acme" }
}

The equivalent direct route binds the identity instead:

POST /api/playbooks/PLAYBOOK_GUID/operations/create_run

{
  "name": "Customer discovery",
  "context": { "customer": "Acme" }
}

Streaming REST/OpenAPI without MCP

Incremental provider responses do not require an MCP connection. Use a scoped playbook API key with the direct vault proxy and set response_mode to stream:

POST /api/playbooks/PLAYBOOK_GUID/secrets/proxy
Authorization: Bearer apb_live_xxx
Content-Type: application/json

This operation is published as proxySecretRequest by the playbook-specific OpenAPI document at GET /api/playbooks/PLAYBOOK_GUID?format=openapi. It forwards supported upstream SSE, NDJSON, JSON, and binary bodies incrementally while keeping the provider credential server-side. It is intentionally separate from the Management API's user-wide credential: use a playbook API key with secrets:read or full permission. See Streaming REST/OpenAPI without MCP for request examples and the full response contract.

Endpoints

Examples

Create a Playbook

curl -X POST https://apbks.com/api/manage/playbooks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Code Review Assistant",
    "description": "Reviews code for bugs and improvements",
    "is_public": false,
    "persona_name": "Senior Developer",
    "persona_system_prompt": "You are a senior software developer with 10+ years of experience. Provide thorough, constructive code reviews.",
    "instructions": "# Project rules\n\n- Use pnpm.\n- Run the tests before committing."
  }'

persona_system_prompt is the agent's identity and travels between projects. instructions holds the always-on operating rules of one project — the content local tools keep in AGENTS.md or CLAUDE.md. Both are stored separately and accepted on create and update; a client that needs a single system prompt receives them composed persona-first.

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "guid": "abc123def456",
  "name": "Code Review Assistant",
  "description": "Reviews code for bugs and improvements",
  "is_public": false,
  "persona_name": "Senior Developer",
  "persona_system_prompt": "You are a senior software developer...",
  "persona_metadata": {},
  "instructions": "# Project rules\n\n- Use pnpm.\n- Run the tests before committing.",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

Add a Skill

curl -X POST https://apbks.com/api/manage/playbooks/$PLAYBOOK_ID/skills \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Code review guide",
    "description": "Use when reviewing code for correctness and security",
    "content": "# Code review\nFollow this checklist...",
    "licence": "MIT",
    "priority": 80
  }'

Update Persona

To update the persona, simply update the playbook:

curl -X PUT https://apbks.com/api/manage/playbooks/$PLAYBOOK_ID \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "persona_name": "Expert Reviewer",
    "persona_system_prompt": "You are an expert code reviewer...",
    "persona_metadata": { "avatar": "👨‍💻" }
  }'

---

MCP Server

The Management MCP Server allows AI agents using the Model Context Protocol to manage playbooks directly. OAuth 2.1 with PKCE is the default for interactive clients; User API Keys remain supported for automation and CI.

Server URL

https://agentplaybooks.ai/api/mcp/manage

Configuration

For Codex / ChatGPT

The AgentPlaybooks Codex plugin already includes the server URL. Codex discovers OAuth automatically and opens the browser consent flow. From the CLI, the same flow can be started explicitly:

codex mcp login agentplaybooks-account

No key is required for this mode. For a headless/CI setup, create a User API Key in Dashboard → Settings and reference it from %USERPROFILE%\.codex\config.toml (Windows) or ~/.codex/config.toml (macOS/Linux):

[mcp_servers.agentplaybooks-account]
url = "https://agentplaybooks.ai/api/mcp/manage"
bearer_token_env_var = "AGENTPLAYBOOKS_API_KEY"

For Claude (claude.ai, Claude Desktop, Cowork)

Remote servers are connected to your Claude account, not configured per app, so the same connector appears on the web, in Claude Desktop and in Cowork. claude_desktop_config.json is for local MCP servers and is not the place for this one.

Pro and Max:

• Go to Customize > Connectors, click + Add, then Add custom connector.
• Name it (for example AgentPlaybooks) and enter the server URL:

https://agentplaybooks.ai/api/mcp/manage

• Review the detected authentication and continue.
• Under OAuth client, choose Register automatically. Our authorization

server supports dynamic client registration, which is what this option uses.

• Click Add, then Connect. Sign in with your AgentPlaybooks account in

the browser and approve access. Claude never sees your password.

Team and Enterprise: an Owner adds the connector first, under Organization settings > Connectors > Add > Custom > Web, with the same URL and the same OAuth choice. Each member then connects individually from Customize > Connectors.

To use it in a conversation, open + > Connectors in the chat and turn AgentPlaybooks on.

Or install the AgentPlaybooks plugin, which adds this same connector together with a skill that teaches Claude how to use your playbooks — see AgentPlaybooks in Claude.

With an API key instead of OAuth: leave authentication on No sign in and add a request header — Authorization: Bearer apb_live_… — under Request headers. Use a User API Key from Dashboard → Settings. This suits a shared or automated setup; for a person, OAuth is better, because revoking access does not mean rotating a key.

Claude connects from Anthropic's cloud, not from your device, so this needs the hosted service (or a self-hosted instance reachable from the internet).

For Claude Code

claude mcp add --transport http agentplaybooks https://agentplaybooks.ai/api/mcp/manage

Then run /mcp inside Claude Code, select agentplaybooks, and follow its sign-in prompt — the browser opens the same consent page. For headless or CI use, pass a User API Key as a header instead:

claude mcp add --transport http agentplaybooks https://agentplaybooks.ai/api/mcp/manage \
  --header "Authorization: Bearer $AGENTPLAYBOOKS_API_KEY"

For Cursor

Add to your MCP settings:

{
  "mcpServers": {
    "agentplaybooks-manage": {
      "url": "https://agentplaybooks.ai/api/mcp/manage",
      "headers": {
        "Authorization": "Bearer $AGENTPLAYBOOKS_API_KEY"
      }
    }
  }
}

Available Tools

The control plane includes account lifecycle tools and the complete canonical playbook tool catalog. Every playbook-scoped tool below requires playbook_id; the direct /api/mcp/:guid endpoint exposes the same schema without that argument.

Example Tool Calls

Create Playbook

{
  "name": "create_playbook",
  "arguments": {
    "name": "My New Assistant",
    "description": "An assistant for helping with daily tasks",
    "is_public": false,
    "persona_name": "Task Helper",
    "persona_system_prompt": "You are a helpful assistant for daily tasks..."
  }
}

Add Skill

{
  "name": "create_skill",
  "arguments": {
    "playbook_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Summarization guide",
    "description": "Use when condensing a long document",
    "content": "# Summarization\nPreserve facts and cite sections...",
    "priority": 70
  }
}

MCP Protocol

The server implements the standard MCP JSON-RPC protocol:

POST /api/mcp/manage
Authorization: Bearer apb_live_xxx
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_playbooks",
    "arguments": {}
  }
}

---

AgentPlaybooks Assistant

We provide a built-in playbook called AgentPlaybooks Assistant that helps AI agents learn how to use the platform. Access it at:

GET /api/playbooks/agentplaybooks-assistant

This playbook includes:

• A persona explaining the platform
• Skills for generating playbook templates
• Documentation and API references

You can use this playbook to bootstrap your AI's understanding of AgentPlaybooks.

---

Best Practices

1. Always Confirm Destructive Actions

Before deleting playbooks, always confirm with the user:

"I'm about to delete the playbook 'My Assistant' and all its contents. This cannot be undone. Proceed?"

2. Use Descriptive Names

// Good
{ "name": "code_review", "description": "Review code for bugs and style issues" }

// Bad
{ "name": "cr", "description": "" }

3. Include Parameter Descriptions

{
  "parameters": {
    "type": "object",
    "properties": {
      "code": {
        "type": "string",
        "description": "The source code to analyze. Can be any programming language."
      }
    }
  }
}

4. Use Memory for Context

Store user preferences, conversation history, or learned patterns in memory. Use tags for categorization and easy search, and descriptions for clarity:

{
  "name": "write_memory",
  "arguments": {
    "playbook_id": "xxx",
    "key": "user_preferences",
    "value": {
      "preferred_language": "Python",
      "code_style": "PEP8",
      "verbosity": "detailed"
    },
    "tags": ["settings", "user", "coding"],
    "description": "User's coding preferences and style settings"
  }
}

Search Memory

Use search_memory to find memories by tags or text:

{
  "name": "search_memory",
  "arguments": {
    "playbook_id": "xxx",
    "tags": ["user", "settings"],
    "search": "preference"
  }
}

This returns all memories that have any of the specified tags AND contain "preference" in the key or description.

Use read_memory when you know the exact key:

{
  "name": "read_memory",
  "arguments": {
    "playbook_id": "xxx",
    "key": "user_preferences"
  }
}

5. Make Playbooks Public Carefully

Only make playbooks public if they're meant to be shared. Public playbooks appear in the marketplace.

---

Playbook MCP Server

Each public playbook has its own MCP server at /api/mcp/:guid. This allows AI clients to:

• Read personas, skills, and memory
• Search memory by tags and text
• Write memory (with API key)
• Access skill attachments

Available Tools (Playbook MCP)

Note: Persona is embedded in the playbook and returned with GET /api/playbooks/:guid

Resources (Playbook MCP)

Example: Point a client at one playbook

A client that signs in with OAuth — Claude, Cursor, VS Code, Claude Code — needs only the URL: https://agentplaybooks.ai/api/mcp/abc123def456. The playbook's Integrations tab has one-click buttons for Cursor and VS Code and the Claude steps.

A client that reads a key from a config file takes it as a header, ideally as a ${VAR} reference the client expands at launch, so no credential reaches the file (apb connect abc123def456 writes exactly this):

{
  "mcpServers": {
    "apb-my-playbook": {
      "type": "http",
      "url": "https://agentplaybooks.ai/api/mcp/abc123def456",
      "headers": {
        "X-API-Key": "${APBKS_KEY_AGENTPLAYBOOKS}"
      }
    }
  }
}

---

Skill Attachments API

Skills can have file attachments (code files, documentation, etc.) that provide additional context.

List Attachments

GET /api/manage/skills/:skillId/attachments

Get Attachment Content

GET /api/manage/skills/:skillId/attachments/:attachmentId
GET /api/manage/skills/:skillId/attachments/:attachmentId?raw=true  # Raw text

Upload Attachment

POST /api/manage/skills/:skillId/attachments
Content-Type: application/json

{
  "filename": "helper.ts",
  "content": "export function helper() { ... }",
  "file_type": "typescript",
  "description": "Helper functions for the skill"
}

Supported file types:

• typescript, javascript, python, go, rust
• sql, markdown, json, yaml
• text, cursorrules, shell

Limits:

• Max file size: 50KB
• Max files per skill: 10
• Max filename length: 100 characters

Update Attachment

PUT /api/manage/skills/:skillId/attachments/:attachmentId
Content-Type: application/json

{
  "content": "updated content...",
  "description": "Updated description"
}

Delete Attachment

DELETE /api/manage/skills/:skillId/attachments/:attachmentId

---

Error Handling

Common errors:

---

Rate Limits

Application-level limits are planned and are not currently guaranteed by the API. Clients should handle 429 Too Many Requests responses with exponential backoff.

---

Security Considerations

• Never expose User API Keys in client-side code
• Use minimal permissions - only request permissions you need
• Set expiration dates for temporary keys
• Rotate keys regularly for long-term use
• Monitor usage via the dashboard