MCP Server

Overview

Polpo exposes a remote Model Context Protocol 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). Clients auto-register on first connect — there is nothing to pre-provision.

GET https://api.polpo.sh/.well-known/oauth-authorization-server

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

Claude Desktop
Cursor
MCP Inspector

Edit your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "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):

{
  "mcpServers": {
    "polpo": {
      "url": "https://api.polpo.sh/v1/mcp"
    }
  }
}

Reload Cursor. Authorize in the browser when prompted.

For debugging and exploration:

npx @modelcontextprotocol/inspector

In the UI:

Transport: Streamable HTTP
URL: https://api.polpo.sh/v1/mcp
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.

CLI

SDKs

Reference

Integrations

Templates

Resources

Overview

Transport

Authentication

Client setup

Available tools

Resources

Prompts

Troubleshooting

​Overview

​Transport

​Authentication

​Client setup

​Available tools

​Resources

​Prompts

​Troubleshooting

Overview

Transport

Authentication

Client setup

Available tools

Resources

Prompts

Troubleshooting