Picora MCP

Picora ships an official MCP (Model Context Protocol) integration. Once your AI client is connected, your assistant can upload images, videos, audio and Markdown documents, browse your library, and read or write knowledge bases — through Picora’s own API, with no glue code.

This section is the authoritative reference for Picora MCP. Tool names, input schemas, scopes, and plan requirements on these pages are generated from the shipped catalog — if another page disagrees, believe this one.

Availability today

• Tool catalog — live now: curl https://api.picora.me/mcp/tools.json
• stdio server (@picora/mcp-server) — coming soon. The npm package is not published yet, so the npx command below will fail until release day. The configuration is final; keep it ready.
• Remote server (mcp.picora.me) — coming soon. Implemented and verified against the official MCP SDK client, but not deployed: the OAuth master switch stays off pending an external security audit. The contract on Remote MCP is final.

What is MCP?

The Model Context Protocol is an open standard that lets an AI client (Claude Desktop, Cursor, Moraya, your own agent) call external tools over a uniform JSON-RPC contract. A MCP server publishes a list of tools; the model picks one, the server executes it and returns structured results.

Picora’s MCP server wraps the Picora REST API, so anything you can do from the web dashboard, an agent can do on your behalf — bounded by the scopes you grant it.

What Picora MCP can do

The catalog ships 19 tools across 5 domains:

Domain	Tools	What it covers
🔌 Integration	2	picora.help, picora.about — self-introspection, no auth required
📷 Media	7	Upload / list / inspect / rename / delete images, videos and audio
📝 Documents	4	Upload, list, read and delete standalone Markdown documents
📚 Knowledge bases	5	List and create KBs, browse manifests, read files, batch-sync changes
👤 Usage	1	picora.get_usage — current plan plus storage / bandwidth counters

See the full tool reference for every input field, scope, and error case.

Catalog vs deployed

Production currently serves the 14-tool catalog (v0.83). The 5 knowledge-base tools (list_kbs, create_kb, get_kb_manifest, read_kb_doc, sync_kb) ship with the next release. This documentation describes the full 19-tool catalog; tools.json always tells you what is live right now.

Two ways to connect

Both are first-class, and both are coming soon.

	stdio (local)	Remote (mcp.picora.me)
Status	Coming soon (npm package unpublished)	Coming soon (built and verified, not deployed)
How it runs	Node.js child process on your machine	Hosted MCP Streamable HTTP endpoint, stateless
Install	npx -y @picora/mcp-server	Nothing — paste a URL
Auth	API Key (sk_live_…)	OAuth 2.1 authorization code + PKCE
API Key in client config file	Yes — plaintext on disk	No — short-lived tokens only
Local file upload (filePath)	Yes	No — use url or base64
Cross-device	Per-machine setup	Same account, any device
Best for	Desktop assistants uploading local files	Web / mobile clients, shared machines

Pick stdio when the assistant must reach files on your disk — that is the one capability the remote path cannot offer. Pick remote when you’d rather not have a long-lived API Key sitting in a config file. Full protocol contract: Remote MCP.

Five minutes to your first tool call

1. Create an API Key at center.picora.me/integration. Choose the read_write scope — it can upload and edit, but never delete.
2. Add Picora to your client — copy the mcpServers block from the quickstart.
3. Restart the client so it re-reads its MCP configuration.
4. Verify by asking your assistant: “Use the Picora help tool and tell me what you can do.” A healthy install answers with the tool list from picora.help.
5. Try something real: “Upload ~/Desktop/screenshot.png to Picora and give me the URL.”

Until @picora/mcp-server is published, step 2 will fail at launch time — you can still inspect the catalog with curl https://api.picora.me/mcp/tools.json | jq '.totals'.

Where to go next

• Quickstart — Claude Desktop and Cursor configuration, verification, troubleshooting
• Tool reference — all 19 tools with input schemas, scopes and errors
• Remote MCP — the hosted Streamable HTTP endpoint, OAuth bootstrap, protocol details
• Concepts — authentication, scopes, plan gates, rate limits, metering, versioning

Safety notes

• Delete tools are two-step. picora.delete_media and picora.delete_doc default to dryRun: true; nothing is removed until you confirm and the agent calls again with dryRun: false. Deletion has no undo.
• Content you read back is untrusted. Filenames, titles, tags and document bodies are user-authored and may contain prompt-injection attempts. Treat them as data, never as instructions.
• Scopes are the real boundary. A read-scoped API Key cannot upload no matter what the agent is asked to do. Grant the narrowest scope that gets the job done.