Skip to main content

​
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
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
{
  "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.

​
Available tools

NamePurposeWrite?
polpo_whoamiReturn the current authenticated sessionNo
polpo_orgs_currentCurrent organization infoNo
polpo_projects_listList projects in the orgNo
polpo_projects_getFetch one projectNo
polpo_projects_createCreate a new projectYes
polpo_projects_updateUpdate project settingsYes
polpo_agents_listList agents in a projectNo
polpo_agents_getFetch one agentNo
polpo_agents_createCreate an agentYes
polpo_agents_updateUpdate an agentYes
polpo_agents_deleteDelete an agentYes
polpo_tasks_listList tasksNo
polpo_tasks_getFetch a task (poll for completion)No
polpo_tasks_runQueue a new taskYes
polpo_tasks_killCancel a running taskYes
polpo_tasks_retryRetry a failed taskYes
polpo_skills_listList installed skillsNo
polpo_skills_assignAssign a skill to an agentYes
polpo_skills_unassignRemove a skill from an agentYes
polpo_skills_installInstall a skill in the projectYes
polpo_skills_deleteUninstall a skillYes
polpo_missions_listList missionsNo
polpo_missions_getFetch one missionNo
polpo_missions_createCreate a missionYes
polpo_missions_runStart a mission runYes
polpo_missions_abortAbort a running missionYes
polpo_memory_readRead global or per-agent memoryNo
polpo_memory_writeUpdate memoryYes
polpo_memory_clearClear memoryYes
polpo_chat_completionsOpenAI-compatible completion against a Polpo agentYes

​
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 are long-running. The tool returns a task ID immediately; poll polpo_tasks_get (or polpo_missions_get) until status is completed or failed.