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. The unscoped URL targets Development for environment projects. Use https://api.polpo.sh/environments/production/v1/mcp when the client must be fixed to Production.

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
GET|POST /environments/{development|production}/v1/mcp — fixed environment endpoint

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_connections_bind`	Bind non-secret trusted Connection scope	Yes
`polpo_connections_grant_slot`, `polpo_connections_revoke_slot`	Manage logical Connection slot grants	Yes
`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

Databases

The following tools manage Databases through the same Data API as the dashboard and SDK. They are also available to the in-product builder. Every call takes projectId (UUID) and optional environment (development, the default, or production). resource is the logical database UUID or name. The project must have Data enabled.

Name	Additional input	Write?
`polpo_databases_list`	None	No
`polpo_databases_get`	`resource`	No
`polpo_databases_create`	`input: { name, schema }`	Yes
`polpo_databases_rename`	`resource`, `input: { name, expectedVersion }`	Yes
`polpo_databases_delete`	`resource`, `expectedVersion`	Yes
`polpo_databases_schema_migrate`	`resource`, `input: { schema, expectedVersion }`	Yes
`polpo_databases_transaction`	`resource`, `input: { operations, idempotencyKey? }`	Yes
`polpo_databases_query`	`resource`, `input: { sql, params?, maxRows?, mode?: "read" }`	No
`polpo_databases_mutate`	`resource`, `input: { sql, params?, maxRows?, idempotencyKey?, mode?: "write" }`	Yes
`polpo_databases_migrations_list`	`resource`	No
`polpo_databases_migrate`	`resource`, `input: { id, expectedVersion, statements, allowDestructive? }`	Yes
`polpo_databases_backend_get`	None	No
`polpo_databases_agent_grants_list`	None	No
`polpo_databases_agent_grants_set`	`agent`, `grants` (replaces all grants; `[]` revokes access)	Yes

MCP uses the authenticated Polpo account. Existing OAuth read/write scopes apply: read-only clients can discover and call the read-only tools, including SQL query; mutations require write access. Account membership and roles still apply. Members can read/write records, while owner/admin accounts manage schemas, migration history, backend state and agent grants. For example, call polpo_databases_query with:

{
  "projectId": "11111111-1111-4111-8111-111111111111",
  "environment": "development",
  "resource": "crm",
  "input": {
    "sql": "SELECT name, email FROM contacts WHERE name = $1",
    "params": ["Maria"],
    "maxRows": 25
  }
}

Use mutate for SQL record writes and migrate for schema changes. Retain the same idempotency key or migration ID and exact input when retrying an uncertain result. These tools use account permissions; the runtime agents’ database_* tools and custom tools’ ctx.data continue to use independent agent grants.

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

Databases

Resources

Prompts

Troubleshooting

​Overview

​Transport

​Authentication

​Client setup

​Available tools

​Databases

​Resources

​Prompts

​Troubleshooting

Overview

Transport

Authentication

Client setup

Available tools

Databases

Resources

Prompts

Troubleshooting