MCP Quickstart

This page gets Picora’s MCP tools into your AI client. It covers the stdio path, which runs @picora/mcp-server as a local subprocess authenticated with an API Key. For the hosted OAuth endpoint, see Remote MCP.

Prerequisites

Node.js ≥ 20 — node --version. The stdio server runs on your machine.
A Picora account — sign up.
An API Key — see below.

Step 1 — Create an API Key

Open center.picora.me/integration and create a new API Key.

Choose the scope. For an AI assistant, read_write is the right default: it can upload and edit, but it cannot delete anything.

Key scope	The agent can	Tools unlocked
`read`	Browse only	list / get / usage tools
`read_write`	Browse, upload, edit	everything except `delete_media` and `delete_doc`
`read_write_delete`	Everything, including permanent deletion	all 19 tools

Copy the key. It starts with sk_live_ and is shown once — store it in a password manager.

Step 2 — Configure your client

Edit the MCP configuration file:

macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
Windows — %APPDATA%\Claude\claude_desktop_config.json
Linux — ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "picora": {
      "command": "npx",
      "args": ["-y", "@picora/mcp-server"],
      "env": {
        "PICORA_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

If the file already has an mcpServers object, add "picora" alongside your existing servers rather than replacing the whole block.

Quit Claude Desktop completely and reopen it — reloading the window is not enough.

Edit ~/.cursor/mcp.json (create it if it doesn’t exist), or use a project-scoped .cursor/mcp.json:

{
  "mcpServers": {
    "picora": {
      "command": "npx",
      "args": ["-y", "@picora/mcp-server"],
      "env": {
        "PICORA_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Restart Cursor, then open the agent panel. Picora’s tools appear in the tool list.

Validate the file first if the server doesn’t show up: jq . ~/.cursor/mcp.json should print without errors. A project-scoped .cursor/mcp.json belongs in .gitignore — it contains your key.

Any client that can launch a stdio MCP server works. Give it:

Command — npx
Arguments — -y @picora/mcp-server
Environment — PICORA_API_KEY=sk_live_…

Or install it globally and point at the binary directly:

npm install -g @picora/mcp-server
PICORA_API_KEY=sk_live_... picora-mcp

To embed the server in your own Node.js process instead of spawning a subprocess:

import { createServer } from '@picora/mcp-server';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = await createServer({ apiKey: process.env.PICORA_API_KEY! });
await server.connect(new StdioServerTransport());

Environment variables

Variable	Required	Default	Notes
`PICORA_API_KEY`	Yes	—	Must start with `sk_live_`. The server refuses to start otherwise
`PICORA_API_URL`	No	`https://api.picora.me`	Use `https://api.picora.cn` for the China region
`PICORA_MCP_UPLOAD_TIMEOUT`	No	`60000` (ms)	Raise it for large uploads on slow links

Step 3 — Verify

Ask your assistant:

Use the Picora help tool and tell me what you can do.

A healthy install calls picora.help — which needs no scope at all — and answers with the tool list. If that works, the transport and the process are fine even before authentication matters.

Then try something that exercises your key:

How much storage am I using on Picora?

That calls picora.get_usage and proves the key is valid and readable. Finally:

Upload ~/Desktop/screenshot.png to Picora and give me the URL.

That calls picora.upload_image with a local filePath and confirms write access.

Troubleshooting

Symptom	Cause and fix
`404 Not Found` from npm when the client starts the server	Expected today — `@picora/mcp-server` is not published yet
Server fails immediately, stderr mentions `PICORA_API_KEY is required`	The key is missing, or doesn’t start with `sk_live_`. Check the `env` block spelling
No Picora tools listed after restart	Invalid JSON in the config file (`jq . <file>`), or the client was reloaded rather than fully quit
Every call returns `MCP_SCOPE_INSUFFICIENT`	The key’s scope is too narrow — a `read` key cannot upload, and only `read_write_delete` can delete
`MCP_PLAN_INSUFFICIENT` on `picora.upload_video`	Video upload requires the Pro plan. Everything else works on any plan
`RATE_LIMITED` during a batch	You hit the tier bucket. Add a delay, or batch differently — see Rate Limits
`QUOTA_EXCEEDED`	Storage or document count is full. Ask the agent to run `picora.get_usage`
The agent invents a tool that doesn’t exist	Check the live catalog: `curl https://api.picora.me/mcp/tools.json \| jq '.tools[].slug'`. Only the 19 documented tools exist

Node.js sends all server logs to stderr, which your client captures — check its MCP log panel first when something is silently broken.

What the server can and can’t touch

It reads only the paths passed explicitly as a filePath argument. There is no directory scan and no shell escape hatch.
It has no telemetry and no analytics.
The API Key is never written to disk by the server itself; it lives only in your client’s config and the process environment.
It exposes exactly the tools in the catalog — nothing else.

Next steps

Tool reference — every input field of all 19 tools
Remote MCP — the hosted OAuth endpoint, no API Key required
Concepts — scopes, plan gates, rate limits, metering