> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polpo.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Server
> Drive Polpo agents from Claude Desktop, Cursor, and any MCP-compatible client.
## Overview
Polpo exposes a remote [Model Context Protocol](https://modelcontextprotocol.io) server at `https://api.polpo.sh/v1/mcp`. It's OAuth 2.0 protected and lets any MCP client — Claude Desktop, Cursor, MCP Inspector, custom agents — list projects, run tasks, manage agents, and call chat completions against your Polpo workspace. Point a client at the URL, complete the OAuth flow, and your agents become callable tools.
## Transport
Streamable HTTP. A single endpoint handles both directions:
* `POST /v1/mcp` — client → server JSON-RPC requests
* `GET /v1/mcp` — server → client SSE stream for progress and notifications
No stdio, no WebSocket. Any client that supports Streamable HTTP MCP transport works.
## Authentication
OAuth 2.0 with Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)). Clients auto-register on first connect — there is nothing to pre-provision.
```http Authorization Server theme={null}
GET https://api.polpo.sh/.well-known/oauth-authorization-server
```
```http Protected Resource theme={null}
GET https://api.polpo.sh/.well-known/oauth-protected-resource
```
Standard MCP clients (Claude Desktop, Cursor, Inspector) discover both endpoints automatically. You'll see a browser window pop up once to authorize; the client stores the token locally and refreshes it silently.
## Client setup
Edit your Claude Desktop config:
* macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
* Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json theme={null}
{
"mcpServers": {
"polpo": {
"url": "https://api.polpo.sh/v1/mcp"
}
}
}
```
Restart Claude Desktop. A browser window opens for OAuth — approve, and `polpo_*` tools appear in the tool picker.
Create `.cursor/mcp.json` at your repo root (or `~/.cursor/mcp.json` for global):
```json theme={null}
{
"mcpServers": {
"polpo": {
"url": "https://api.polpo.sh/v1/mcp"
}
}
}
```
Reload Cursor. Authorize in the browser when prompted.
For debugging and exploration:
```bash theme={null}
npx @modelcontextprotocol/inspector
```
In the UI:
1. Transport: **Streamable HTTP**
2. URL: `https://api.polpo.sh/v1/mcp`
3. Click **Connect** and complete the OAuth flow.
You can now list tools, invoke them with custom args, and inspect raw JSON-RPC traffic.
## Available tools
| Name | Purpose | Write? |
| ---------------------------------------------------------------------------- | -------------------------------------------------- | ------ |
| `polpo_whoami` | Return the current authenticated session | No |
| `polpo_orgs_current` | Current organization info | No |
| `polpo_projects_list` | List projects in the org | No |
| `polpo_projects_get` | Fetch one project | No |
| `polpo_projects_create` | Create a new project | Yes |
| `polpo_projects_update` | Update project settings | Yes |
| `polpo_loops_list`, `polpo_loops_get` | Inspect project loop definitions | No |
| `polpo_loops_create`, `polpo_loops_update`, `polpo_loops_delete` | Manage project loops | Yes |
| `polpo_loop_permissions_list`, `polpo_loop_hooks_list` | Inspect loop permission and hook catalogs | No |
| `polpo_connections_providers`, `polpo_connections_list` | Inspect provider and project connections | No |
| `polpo_agents_list` | List agents in a project | No |
| `polpo_agents_get` | Fetch one agent | No |
| `polpo_agents_create` | Create an agent | Yes |
| `polpo_agents_update` | Update an agent | Yes |
| `polpo_agents_delete` | Delete an agent | Yes |
| `polpo_tasks_list` | List tasks | No |
| `polpo_tasks_get` | Fetch a task (poll for completion) | No |
| `polpo_tasks_run` | Queue a new task | Yes |
| `polpo_tasks_kill` | Cancel a running task | Yes |
| `polpo_tasks_retry` | Retry a failed task | Yes |
| `polpo_skills_list` | List installed skills | No |
| `polpo_skills_get` | Fetch a skill | No |
| `polpo_skills_create` | Create a project skill | Yes |
| `polpo_skills_assign` | Assign a skill to an agent | Yes |
| `polpo_skills_unassign` | Remove a skill from an agent | Yes |
| `polpo_skills_install` | Install a skill in the project | Yes |
| `polpo_skills_delete` | Uninstall a skill | Yes |
| `polpo_missions_list` | List missions | No |
| `polpo_missions_get` | Fetch one mission | No |
| `polpo_missions_create` | Create a mission | Yes |
| `polpo_missions_run` | Start a mission run | Yes |
| `polpo_missions_abort` | Abort a running mission | Yes |
| `polpo_memory_read` | Read global or per-agent memory | No |
| `polpo_memory_write` | Update memory | Yes |
| `polpo_memory_clear` | Clear memory | Yes |
| `polpo_vault_list` | List legacy vault metadata | No |
| `polpo_vault_delete` | Delete a legacy vault entry | Yes |
| `polpo_tools_list`, `polpo_tools_get` | Inspect custom tools | No |
| `polpo_tools_create`, `polpo_tools_delete` | Manage custom tools | Yes |
| `polpo_schedules_list` | List mission schedules | No |
| `polpo_schedules_create`, `polpo_schedules_update`, `polpo_schedules_delete` | Manage mission schedules | Yes |
| `polpo_teams_list` | List teams | No |
| `polpo_teams_create`, `polpo_teams_update`, `polpo_teams_delete` | Manage teams | Yes |
| `polpo_models_search`, `polpo_models_get` | Search and inspect the model catalog | No |
| `polpo_chat_completions` | OpenAI-compatible completion against a Polpo agent | Yes |
## Resources
Polpo exposes resource URIs for deep context without tool calls:
```
polpo://projects/{id}
```
Returns the full project config — agents, skills, tools, environment, deploy status — as a single JSON document. Useful for letting an MCP client load a project into context in one shot.
## Prompts
Reusable prompt templates are exposed under the `prompts/` namespace:
* **`polpo_setup_project({ goal })`** — guides the creation of a new Polpo project end-to-end. Takes a free-form goal (e.g. *"customer support agent with Zendesk access"*) and walks through project creation, agent definition, tool selection, and deploy.
## Troubleshooting
**401 Unauthorized** — OAuth token expired. Re-authorize from your client (Claude Desktop: toggle the server off/on; Cursor: re-open the MCP config).
**403 Forbidden** — Token is valid but missing scope for the resource. Check the org/project you're targeting matches the authorized session (`polpo_whoami`, `polpo_orgs_current`).
**Project 404** — The project ID doesn't exist in the current org. Call `polpo_projects_list` first to get a valid ID.
**Tool call timeout** — `polpo_tasks_run` and `polpo_missions_run` start asynchronous work. Poll `polpo_tasks_get` until a task is `done` or `failed`, or `polpo_missions_get` for mission status.