One account. 300+ MCP tools. Right inside your chat tool.

Errors

A tool error comes back as an MCP tool result with isError: true. The same JSON object is in structuredContent and in the first text content block:

{
  "error_code": "WORKSPACE_ACCESS_DENIED",
  "code": "WORKSPACE_ACCESS_DENIED",
  "message": "This connection has no access to this workspace.",
  "details": {
    "error_code": "WORKSPACE_ACCESS_DENIED",
    "workspace_id": 12345
  },
  "hint": "Use po_workspaces_list to see the workspaces this connection can access. Retrying will not change the result."
}

error_code

Stable machine-readable code. It is mirrored in code and details.error_code because some clients rewrite error_code.

message

Human-readable explanation.

details

Context such as http_status, retryable / retry_safe, suggested_backoff_ms, validation_errors or the IDs that were sent.

hint

What to do next, written for the model.

retryablehttp_status

Optional top-level fields declared in the output schemas.

Not an error: when a file input is missing, the file-based tools (extraction, PDF) return a normal text result that starts with FILE_UPLOAD_REQUIRED and names the accepted inputs or a browser upload page.

On the transport level, a missing, invalid, expired or revoked token gets HTTP 401 with a WWW-Authenticate header (run OAuth again). While authentication or the tool catalog is briefly unavailable, the server answers HTTP 503 with Retry-After (2–5 s).

Rate limits and quotas

• Per MCP session (Mcp-Session-Id): at most 8 tool calls in flight. Tools with 1 in the last column run one at a time: a second concurrent call returns SESSION_BUSY at once (retry after about 300 ms, or 500 ms for po_knowledge_graph_ask). The other tools run up to 4 in parallel and wait up to 15 s for a free slot.
• Per access token across all sessions: at most 24 tool calls in flight (ACCOUNT_BUSY).
• The request limits of the PaperOffice API apply to every tool call: free and visitor tokens get at least 5 requests per second, 30 per minute, 100 per hour and 500 per day; plan values can be higher. Paid plans with remaining credits are limited by credits, not by a request rate. Rate-limited calls are not charged; they return TRANSIENT_TRANSPORT_ERROR with details.http_status 429 and the wait time in the message.
• Time limits: a backend call is abandoned after 90 s (knowledge base writes then return WRITE_OUTCOME_UNKNOWN or TRANSLATION_IN_PROGRESS instead of retrying blindly); po_knowledge_graph_ask stops after 120 s.
• Limits stated in the tool descriptions: up to 10 files per po_documents_upload_files call (/chatgpt only), 2 or more PDFs per merge, up to 500 search hits per page, up to 200 workspaces per page and 10–200 recycle-bin entries per page. Download links expire after about 10 minutes, and a claimed task stays locked for 15 minutes.
• Billing: MCP calls are billed in credits like REST API calls. Tools whose description says “costs credits” or “uses credits” start AI processing and use more credits.