MCP server

The MCP server exposes the Developer API as Model Context Protocol tools over streamable HTTP. Use the same API keys as the REST surface.

The MCP endpoint is served at https://sapien-poq.up.railway.app/mcp.

The server is stateless, so nothing is managed across requests. Project and upload tools share domain logic with /developer/v1; field names, pagination cursors, and error vocabulary match.

Authentication

Every request needs a bearer token in the Authorization request header:

Authorization: Bearer poq_live_...

See API keys for key creation and lifecycle. Project tools additionally require the key creator to be an org originator, the same rule as the Developer API. Unauthenticated requests receive a JSON 401 before any MCP dispatch.

Client setup

Example for Cursor (mcp.json):

{
  "mcpServers": {
    "sapien-poq": {
      "type": "http",
      "url": "https://sapien-poq.up.railway.app/mcp",
      "headers": {
        "Authorization": "Bearer poq_live_..."
      }
    }
  }
}

Other MCP clients (Claude Code, VS Code) use the same URL and header pattern.

Tools

Project and upload tools

These mirror the Developer API 1

Instruction and convenience tools

These have no REST counterpart.

Uploading data

Bytes never flow through a tool call. create_upload_session and declare_upload_files return a presigned PUT URL per file. Upload each file with a plain HTTP PUT to that URL (no Authorization header), then call process_upload_session and poll status.

The REST one-shot PUT .../file redirect has no MCP equivalent. It is HTTP transport sugar for curl -T. Use declare_upload_files instead.

Errors

Domain failures return tool errors (isError: true). The text leads with a stable camelCase code:

projectNotFound: Project not found.

requestId: 0192f0a0-...

Codes are the camelCase spellings of the REST catalog (projectSpecInvalid ↔ project_spec_invalid, notOrgOriginator ↔ not_org_originator). Map handling the same way across both surfaces.

Include the requestId block when reporting issues. It matches the X-Request-Id header on REST responses.

REST vs MCP

See also