> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parable.work/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

## Sources

Docs: [Workspace API MCP reference](/protocols/_generated/mcp/web-api)

Web App: Workspace managers configure Ponder tool permissions in the
[Persona editor](/ponder/personas); standalone MCP hosts use their own tool and
confirmation experience.

Parable MCP connects assistants and developer tools to Workspace and Admin
operations through the same generated contracts used by HTTP and the SDKs.
Every Workspace operation has an explicit MCP classification. Most product
operations are available to discovery; browser callbacks, secret exchange,
machine plumbing, Ponder control-plane routes, and unsupported multipart
operations are explicitly hidden.

Four schema declarations keep the tool surface understandable:

* `@docs` supplies the display title, description, capability, lifecycle, and
  audience shared across protocol references;
* `@icon` supplies the Font Awesome glyph;
* `@mcp` supplies the stable lowercase handle, visible-or-hidden decision, and
  default Ponder policy; and
* the route's permission declaration and behavior remain the authority for
  what a person can read or change.

A catalog entry never grants access. Search omits operations the current person
cannot use, and the generated API route checks authentication, permission,
resource ownership, state, and revision again when invoked.

## Discover tools without loading the whole catalog

Standalone MCP sessions keep environment, Workspace, authentication, and
catalog tools available. After authentication:

1. Search with `tool_search`. Results contain lightweight titles,
   descriptions, icons, and handles, not every JSON Schema.
2. Enable a selected operation with `tool_enable`.
3. The session publishes the enabled generated tool and sends
   `notifications/tools/list_changed`.
4. Authentication, logout, Workspace changes, and permission refresh reconcile
   the session's enabled tools.

Session activation is isolated: enabling a tool in one MCP connection does not
publish it in another. Standalone MCP does not apply Ponder Persona policy; the
MCP host owns its confirmation experience.

Ponder uses the same Workspace catalog through three internal helpers: search,
inspect one exact schema, and execute an inspected operation. It never places
the complete catalog in model context. A Persona-wide policy can narrow each operation
to **Never**, **Ask**, or **Always**, but that policy cannot grant an operation
the initiating person lacks.

## Approvals in Ponder

* **Never** omits the operation from that Persona's search.
* **Ask** pauses the tool call in the Message and offers **Deny once** and
  **Allow once**.
* **Always** continues without a separate Ponder prompt.

Workspace managers can remember Always or Never for the Persona or Workspace
default. The policy write must commit before the pending call continues.
Signed approval state binds the person, Problem, Message, Persona, execution
profile, catalog schema, arguments, and current policy. The accepted model and
text configuration are retained across the pause; changing a ranking does not
silently switch providers during continuation. The browser receives only a safe
title, consequence, bounded summary, and opaque approval identity.

HTTP paths, operation IDs, and SDK method names remain independent compatibility
identifiers. A tool handle does not rename those surfaces.

## Local stdio

The local stdio server keeps authentication and Workspace selection inside the
MCP session, then forwards enabled operations through generated SDK dispatch. In a derived
worktree it replaces the checked-in development URLs only when both API
endpoints resolve from `WEB_API_URL` and `WEB_ADMIN_API_URL`, or from the paired
`WEB_API_PORT` and `WEB_ADMIN_API_PORT` values. A partial or invalid override
fails startup instead of mixing services from different checkouts.

Source the worktree stamp before running the Vercel AI SDK smoke:

```bash theme={null}
source .env.wt
cd apps
bun run --cwd ponder-api smoke:mcp
```

The smoke initializes the real stdio transport and sends a read-only sentinel
health call to the worktree Admin API. The session deliberately has no bearer
token, so success means the API request occurred and returned the server's
sanitized refusal. The smoke never prints or persists a credential or the
underlying API response.

<Note>
  The Mintlify documentation MCP is a separate, hosted interface for reading
  these docs.
</Note>