Skip to content
  • Follow System
  • English
  • 中文

AI Workflows — Overview

Picora is positioned as a resource hosting platform for AI workflows. This page explains the why — what the integration buys you, what protects you, and when to reach for the plain API instead.

What is MCP?

Model Context Protocol is an open standard that defines how AI assistants (Claude, Cursor, Moraya, …) call external tools. Think of it as a “USB for AI tools”: once a tool exposes an MCP server, any MCP-compatible client can use it.

Picora exposes 19 MCP tools across five domains — integration (2), media (7), documents (4), knowledge bases (5) and usage (1). Together they cover the full resource lifecycle: upload, list, inspect, rename, sync, and delete.

Why use Picora through AI?

Common workflows an assistant can complete via Picora MCP:

PromptWhat happens
”Upload the README I’m editing to Picora and give me a public link.”The assistant calls picora.upload_doc with the current file, receives a stable URL, and pastes it into your message.
”List my videos uploaded this week, sorted by size.”It calls picora.list_media with type: "video" and renders a table.
”I’m running low on image storage — show me the largest 20 images.”It calls picora.list_media, sorts by sizeBytes, displays results.
”Replace the URL in my blog post with a fresh upload of assets/cover.png.”It calls picora.upload_image, then helps you edit the post.
”Make that screenshot private.”It calls picora.update_media with isPublic: false.
”Clean up videos older than 90 days, but show me the list first.”It calls picora.delete_media with dryRun: true, asks for confirmation, then re-runs with dryRun: false.
”What changed in my notes KB since Monday?”It calls picora.get_kb_manifest with since, then picora.read_kb_doc on the paths that moved.

This is real productivity — you no longer copy/paste URLs or upload assets one at a time.

Two ways to connect

Picora exposes MCP over two transports. Both are first-class; both are coming soon (the npm package is unpublished and the remote endpoint is not yet deployed).

ModeTransportAuthenticationBest for
stdio@picora/mcp-server as a local child processAPI Key (sk_live_…)Assistants that must read files off your disk
RemoteStreamable HTTP at mcp.picora.meOAuth 2.1 authorization code + PKCEWeb / mobile clients, shared machines, no key on disk

The decisive difference: only stdio can accept a local filePath. Everything else is a matter of taste. The full comparison, the configuration snippets and the current status are on MCP and Remote MCP.

Architecture

┌─────────────────────┐
│ Claude Desktop /    │
│ Cursor / Moraya     │
└──────────┬──────────┘
           │ MCP protocol (JSON-RPC over stdio or Streamable HTTP)
           │
   ┌───────┴───────┐
   │               │
┌──▼───────────┐  ┌▼─────────────────┐
│ stdio        │  │ Remote           │
│ @picora/     │  │ (mcp.picora.me)  │
│ mcp-server   │  │ OAuth 2.1        │
└──┬───────────┘  └┬─────────────────┘
   │               │
   └───────┬───────┘
           │ HTTPS + Bearer auth
           ▼
   ┌──────────────────┐
   │ Picora API       │
   │ api.picora.me    │
   │ /v1/*            │
   └──────────────────┘

Both modes ultimately call Picora’s /v1/* API. The difference is transport + auth:

  • stdio runs on your machine, holds the API Key, talks HTTPS to api.picora.me
  • Remote runs on our servers, verifies your OAuth access token, then calls the API internally

Security model

Prompt-injection protection

User-uploaded resources (filenames, titles, tags, Markdown content) can contain prompt-injection payloads. Picora protects you on multiple layers:

FieldProtection
FilenameSanitized (control chars + suspicious sequences stripped) before being returned to the model
Title / tagsSame sanitization
Document contentNot sanitized (that would corrupt user-authored text) — instead every tool that returns content carries an explicit warning in its description telling the model to treat it as data
Image / video / audio binaryCannot carry prompt-injection text

Modern AI clients surface these warnings to the model and instruct it to treat user content as data, not commands. The client is the last line of defence.

Scopes

Every tool declares the scopes it needs, in dot notation — media.read, media.write, media.delete, kb.read, kb.write, usage.read, account.read. An API Key’s tier expands into the same scope set that an OAuth grant carries, so the two credential types behave identically.

Two tools — picora.help and picora.about — declare no scope at all, which is why “ask the assistant to call picora.help” is the standard smoke test.

Scope is a hard boundary: a read-scoped key cannot upload no matter how the request is phrased. The full mapping is in MCP → Concepts.

Dry-run safety

Both delete tools default to dryRun: true. The first call shows what would be deleted; the assistant must explicitly retry with dryRun: false to actually delete. This prevents conversational misunderstandings from causing data loss — and deletion has no undo.

What’s not in MCP

We deliberately keep MCP focused on resource management. Things that are not exposed:

  • Account / profile editing — too risky for an agent to change your account
  • Billing / subscription changes — an agent shouldn’t trigger payments
  • API Key creation — keys are sensitive; create them in the dashboard

If you need any of these, do them in the dashboard.

Comparison with the raw API

ConcernDirect API callMCP
Setupcurl / requests / the SDKAdd config to your AI client
AuthAPI Key in headersAPI Key (stdio) or OAuth flow (remote)
DiscoverabilityRead the OpenAPI specThe client lists tools and infers usage
SafetyNoneDry-run, prompt-injection warnings, scope gates
Best forProduction scripts, custom toolsInteractive AI sessions

You can use both — direct API in your CI pipeline, MCP in your daily AI sessions.