MCP Concepts

This page is for AI engineers and product owners trying to decide how to integrate Picora’s MCP server. If you just want to wire it up, jump to Claude Desktop or Cursor.

What is MCP?

The Model Context Protocol (modelcontextprotocol.io) is an open spec that lets an AI client (Claude Desktop, Cursor, Continue, your own agent) talk to a tool server with a uniform JSON-RPC contract. The server lists “tools” (atomic actions like upload-image), the client picks one, and the server runs it.

Picora’s MCP server at mcp.picora.me wraps the public REST API and exposes 30 fine-grained tools. Authentication is OAuth 2.1 + PKCE — same flow as the rest of Picora’s first-party SSO (see Authentication).

Why we split into 30 tools

Earlier Picora versions exposed a handful of broad tools (picora.search, picora.upload). v0.33 splits them into 30 narrowly-scoped tools because:

Better tool discovery for AI agents. A model picks picora.upload_image faster from a sharply-named list than it figures out which combination of args to a generic picora.upload is needed.
Per-tool rate-limit tier. Each tool declares whether it counts against read / mutation / upload. Aggregating into one tool would force the strictest tier on everything.
Plan gating. picora.upload_video requires Pro plan; picora.list_watermark_templates requires Pro+. A 30-tool catalog lets the marketplace UI show “you can call X with your plan, Y is locked” precisely.

Scope mapping

Every tool declares its required OAuth scopes (the catalog is in tools.json). Common patterns:

Token scope	What you can do
`media.read`	List, fetch, search images / videos / audio
`media.write`	Upload, change visibility, set hotlink rules
`media.delete`	Permanently delete
`kb.read` + `kb.write`	KB CRUD + document CRUD inside KBs
`account.read` + `usage.read`	Read profile, plan, storage / bandwidth counters

Picora resolves v0.30 colon-style aliases (read:media → media.read), so older OAuth clients keep working.

Plan gate

Some tools require a higher plan than the user’s current plan, regardless of scope:

Tool	Required plan
`picora.upload_video`	`pro`
`picora.list_kbs` and KB writes	`pro`
`picora.list_watermark_templates`	`pro_plus`

When a pro_plus-only tool is called by a pro user with the right scope, the response is MCP_PLAN_INSUFFICIENT with meta.required = "pro_plus" so your agent can prompt the user to upgrade.

Order of checks (designed-in):

Tool exists in catalog? (else MCP_TOOL_NOT_FOUND)
Token scope sufficient? (else MCP_SCOPE_INSUFFICIENT)
Plan satisfies requiredPlan? (else MCP_PLAN_INSUFFICIENT)
Rate-limit window OK? (else RATE_LIMITED)
Run the tool — propagate API errors as MCP_HANDLER_ERROR if 5xx, otherwise pass through code.

Deprecation lifecycle

When Picora renames or replaces a tool, it follows a predictable lifecycle so you have time to migrate:

v(N)   tool flagged deprecated, replaceWith=<new slug>, removeIn=v(N+1)
       ↓
       Calls still work
       Response body adds _deprecation
       HTTP headers add Deprecation: true + Sunset: <date>
       Admin dashboard surfaces 24 h call counts to ops

v(N+1) tool removed
       Calls return HTTP 410 Gone with code=MCP_TOOL_REMOVED + meta.replaceWith

Removal is delayed by one extra minor version if the tool still has > 100 calls per 24 h at the planned removal date — Picora ops is expected to email the affected clients first.

What is not logged

Picora logs tool_slug / client_id / latency_ms / status / error_code for each invocation, retained for 90 days for ops triage and abuse detection. The server does not log:

Tool arguments (prompts, file contents, KB document text)
Response bodies
Bearer tokens

Standard data-protection guarantees apply: GDPR for the global deployment, PIPL for the China deployment.

Choosing the right tool

If your agent needs to know “what can I do here?” at runtime, call picora.help (no scope required). The response includes the same content as tools.json — slug, description, scopes, examples. Use that to drive function-calling prompts dynamically rather than hard-coding tool names.