Tool catalog (v0.2)

Pad’s remote MCP server at mcp.getpad.dev/mcp 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 (8 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.2).
• 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.2", "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.2", "cmdhelp_version": "0.1" }

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

Pin against tool_surface_version: "0.2" 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 index page’s authentication overview 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_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

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://_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.2 catalog over stdio.

← MCP index · Troubleshooting →