MCP reference

OpenApps MCP reference.

The contract for https://mcp.openapps.network/connect, the one connection for every app: transports, protocol versions, sign-in, scopes, the six tools, and the shape of results and errors. For a walkthrough, read the agents guide first.

Last updated: 5 October 2026

Endpoint and protocol.

Addresses on this host.

One host, one address per connection. No address is a prefix of another, so a token issued for one is never accepted at another.

The host's other paths (/authorize, /token, /register, /revoke, the approval pages under /connect/…, /v1/…) are part of sign-in and runs, not MCP connections.

Discovery.

Authorization.

OpenApps MCP is an OAuth 2.1 resource server, as the MCP authorization spec describes. The issuer is https://mcp.openapps.network, and the people behind each connection sign in with OpenWallet ID.

Without a token you may call server/discover, tools/list, openapps_find and openapps_feedback, at a lower rate limit. Anything else without the right token answers 401, or 403 if a scope is missing, with a header saying what to ask for:

WWW-Authenticate: Bearer resource_metadata="https://mcp.openapps.network/.well-known/oauth-protected-resource/connect", scope="apps:run"

Scopes

The six tools.

Descriptions are fixed: they never include a caller's limits, today's prices or the size of the catalogue. The list is sorted by name, marked cacheScope: "public", and cached for a day.

openapps_start is marked destructive because a charge cannot be undone by the caller. A failed run is refunded by the system.

openapps_find

Search the catalogue, or fetch one operation's full contract.

{ "query": "split this PDF into invoices and pull the totals",
  "filters": { "app": ["openextract"], "max_price_usd": 0.5,
               "effects": ["reads", "writes"], "runs_on": "remote" },
  "limit": 5,          // 1–10
  "cursor": "…" }

// or, for one operation's full contract:
{ "detail": "doc.extract_to_schema" }

Returns compact cards (id, app, title, summary, price.typical_usd, price.p95_usd, grade, effects, runs_on), total_matches and next_cursor. Signed in, it also returns the account's credits and remaining limits. When nothing matches, no_match suggests near misses. Queries can be in any of our eight languages.

openapps_plan

Turn a job and its inputs into a priced plan.

{ "intent": "one PDF per invoice, with the totals",
  "files": [ { "file_id": "f_…" } ],     // or { "url": "https://…" }
  "policy": "balanced" }                 // best | balanced | cheapest

Returns plan_id, the quote, its classification, and needs_upload: a list of { name, accept, max_bytes, upload_url } for inputs still missing. A file path is refused.

openapps_start

{ "plan_id": "pl_…",
  "authorization": { "kind": "credits" },              // OpenApps credits
              // or { "kind": "openwallet", "max_usd": 0.5 }   device-approved
  "idempotency_key": "…",                              // required
  "events": true }                                     // optional AG-UI stream

Returns at once: run_id, state (queued, awaiting_approval or running), approval (url, expires_at) when the person must approve, events_url, and poll_after_ms. The same idempotency key for the same plan returns the same run.

openapps_status

{ "run_id": "run_…", "wait_ms": 30000 }. Holds for up to 45 seconds and returns as soon as the run changes: its state, step progress, what has been charged, and finished results as resource_links valid for one hour.

openapps_receipt

{ "run_id": "run_…" }. The Ed25519-signed receipt and how to verify it offline. The public keys are at https://mcp.openapps.network/v1/keys.

openapps_feedback

A report (kind, about, summary, details, expected, actual, error_code, contact_ok) returns ticket_id and status_url. { "ticket_id": "fb_…" } returns its state: received, triaged, planned, fixed_in a version, or wont_fix with a reason. The same report is accepted without MCP at POST https://mcp.openapps.network/v1/feedback. Limits: 20 reports an hour per token, 5 when anonymous.

Results and errors.

• Structured results come in structuredContent, matching the tool's outputSchema. The text block is a one-line summary, not the same JSON again.
• Every result carries _meta["network.openapps/manifest"], the SHA-256 of the canonical tool list. If it changes, the tools changed.
• A malformed request or an unknown tool is a JSON-RPC -32602.
• Bad arguments, refusals and failures are a result with isError: true and structuredContent: { code, message, retryable, details? }. code is stable and snake_case; message is for people.

MCP servers inside the apps.

Building Some apps also ship their own MCP server that runs on your machine over stdio, for people who run the app locally: OpenPdfEdit, OpenRedact, OpenExtract, OpenOCR, OpenSlides, OpenPhotoEdit and others. Each will document its own install line when it ships. They all follow the same rules, so an agent that has used one knows them all:

• Tool names are lower snake_case, verb first, and say what they act on: redact_pdf, list_ocr_operations, undo_photo_edit.
• Every tool has a title and all four annotations, and they are true.
• At most fifteen tools by default; more sit behind a start-up flag.
• They read and write only inside the folders you name when you start them, and take paths in and give paths out.
• Credentials, signing keys and which programs to run come from start-up flags or the environment, never from a tool argument the model fills in.
• Each has a report_problem tool. A local server never sends anything on its own: it sends a report only if you started it with --feedback or you confirm, and otherwise hands you the finished report to send yourself.