Tool catalog (v0.3)

Pad’s remote MCP server at https://mcp.getpad.dev advertises a hand-curated catalog of resource × action tools. Each top-level tool takes an action enum that selects the operation, plus action-specific parameters. This shape keeps the surface compact (9 tools in the agent’s tool list, not 80+) without losing access to any individual capability.

The contract is versioned. Two independent version tiers are advertised:

• padToolSurface — the MCP tool catalog shape (this page documents v0.3).
• padCmdhelp — the underlying CLI help-tree shape (currently "0.1"). Bumps independently from the tool surface.

The handshake’s result.capabilities.experimental block carries both:

{
  "result": {
    "capabilities": {
      "experimental": {
        "padToolSurface": { "version": "0.3", "tool_surface_stable": true },
        "padCmdhelp":     { "version": "0.1", "tool_surface_stable": true }
      }
    }
  }
}

The same values are also reachable two other ways:

• Read the pad://_meta/version resource:

  { "tool_surface_version": "0.3", "cmdhelp_version": "0.1" }

• Call the pad_meta tool with action: version — same payload as the resource.

Pin against tool_surface_version: "0.3" if you’re building a downstream consumer. Breaking changes bump the version and are announced on the blog before they ship.

Capability scopes

Every tool action is gated by one of three scopes:

Scope	Example actions
pad:read	pad_item.list, pad_item.get, pad_search.query, pad_project.dashboard
pad:write	pad_item.create, pad_item.update, pad_item.comment, pad_item.bulk-update
pad:admin	pad_workspace.invite, pad_collection.create, pad_role.create

A token’s scope is set at consent time and is bounded by your role in each workspace at call time. See the Remote MCP overview’s authentication section for the full model.

Tools

pad_set_workspace

Sets the active workspace for the rest of the conversation. After calling this, every subsequent tool call defaults to that workspace unless you explicitly pass a different one via the workspace parameter.

Parameter	Type	Description
workspace	string	Workspace slug (e.g. my-project)

Returns: the workspace’s { slug, name, role } for confirmation.

pad_item

Items are the universal unit: tasks, ideas, plans, docs, and any custom collections you’ve defined. References use issue IDs (TASK-5, BUG-12, PLAN-3).

Action	Scope	Notes
list	read	List items, filter by collection / status / priority / parent / role / assignee
get	read	Show full item including content, comments, links
create	write	Create an item; specify collection, title, optional fields
update	write	Partial update; pass comment to capture why (also how role assignment happens — set role to a role slug)
delete	write	Archive (soft delete)
move	write	Move between collections
link	write	Create a relationship — see link_type enum below
unlink	write	Remove a relationship of a given link_type
deps	read	Show dependency graph for an item
star / unstar	write	Personal-pin (per user, per item)
starred	read	List your starred items
comment	write	Add a comment, optionally a reply via reply_to
list-comments	read	Read the comment thread
bulk-update	write	Apply the same patch to multiple items (refs: array<string>)
note	write	Append an implementation_notes entry
decide	write	Append a decision_log entry

link_type enum (for link / unlink): blocks, blocked-by, supersedes, implements, split-from. Full-text search over items is exposed separately as pad_search.query — not as a pad_item action.

pad_workspace

Action	Scope	Notes
list	read	List workspaces this token can access
members	read	List members of a workspace
invite	admin	Invite a user by email
storage	read	Workspace storage usage (items, attachments, etc.)
audit-log	read	Workspace audit-log entries (filter by audit_action)

pad_collection

Collections are typed item containers (Tasks, Ideas, Plans, Docs by default; custom collections supported).

Action	Scope	Notes
list	read	List collections in the workspace with their schemas + counts
create	admin	Define a new collection (typed fields via the field DSL)

pad_project

Higher-level intelligence tools that aggregate across collections.

Action	Scope	Notes
dashboard	read	Active items, plans, attention items, suggestions
next	read	Recommended next task (role-aware if role is set)
standup	read	Recently completed / in-progress / blockers (configurable lookback)
changelog	read	Release notes from completed items (range-filterable)

pad_role

Pad’s agent-role system (Planner, Implementer, Reviewer, etc.) lets users organize work by what kind of thinking it requires.

Action	Scope	Notes
list	read	List workspace roles
create	admin	Define a new role (slug, name, optional icon + description)
delete	admin	Remove a role

Role assignment is not a pad_role action — assign items to a (user, role) pair via pad_item.action: update with the role and assign parameters.

pad_search

Action	Scope	Notes
query	read	Full-text search across items in the workspace

Returns: { items, total }. Cross-collection by design.

pad_playbook

Playbooks are workspace-owned, user-invokable procedures. The MCP tool mirrors pad playbook (list / show / run) so a remote agent can browse and execute playbooks the same way a local CLI user does.

Action	Scope	Notes
list	read	Workspace playbook metadata (slug, invocation_slug, trigger, status, has_arguments, summary). Same shape as the bootstrap response
get	read	Full body + fields for one playbook; accepts invocation_slug, item slug, or issue ref
run	read	Parse args against the playbook’s declared spec and return the body + bound args + any unbound required args. Side-effect-free — the server never executes a playbook; the agent reads the body and runs the steps

For action: run, pass either:

• args (object) — pre-parsed argument map keyed by name, OR
• raw_args (array of strings) — CLI-style tokens (positional values, bareword flags, key=value pairs); the server applies the same strict parser as pad playbook run.

The two forms are mutually compatible — explicit args take precedence over raw_args on key conflicts.

See Playbooks → for the author guide.

pad_meta

Action	Scope	Notes
server-info	read	Server name + runtime version (lightweight, no params)
version	read	Full version metadata: pad version, cmdhelp_version, tool_surface_version, MCP protocol version (same JSON as pad://_meta/version)
tool-surface	read	Catalog dump: every tool, action, and input schema
bootstrap	read	One-shot workspace overview: workspace + user + collections + always-on conventions + roles + playbook metadata + dashboard + recent activity. Equivalent to pad://workspace/{ws}/bootstrap and to pad_set_workspace’s embedded response

Resources

The MCP resources/list surface exposes:

• pad://workspaces — list of workspaces this token can access (top-level, server-wide)
• pad://workspace/{ws}/items/{ref} — a single item
• pad://workspace/{ws}/items — all items in a workspace
• pad://workspace/{ws}/dashboard — the dashboard payload (same as pad_project.dashboard)
• pad://workspace/{ws}/collections — collection list
• pad://workspace/{ws}/bootstrap — one-shot workspace overview (same as pad_meta.bootstrap and pad_set_workspace’s embedded response)
• pad://_meta/version — server-wide version + contract metadata

Resources are read-only and cheaper for an agent to inspect than calling a tool.

Prompts

Pad ships four MCP prompts (multi-step workflows the agent can run on demand):

• pad_plan — guided plan creation
• pad_ideate — brainstorming workflow that captures ideas at checkpoints
• pad_retro — retrospective for a completed plan
• pad_onboard — codebase analysis + workspace setup

These are the same workflows the local /pad skill exposes. The remote MCP server hands them to any client that supports prompts/get.

Going deeper

• The Go source of the catalog is at internal/mcp/catalog_*.go. Each pad_<resource> is its own file.
• For local-machine MCP (no account, runs against a SQLite file on your laptop), see MCP — Local. It exposes the same v0.3 catalog over stdio.

← Remote MCP overview · Troubleshooting →