MCP reference

Orcha provides a Model Context Protocol (MCP) server that allows AI agents to interact with context files and structured databases within a workspace using the standardized MCP protocol.

Endpoint: POST https://app.tryorcha.com/mcp

Transport: Stateless Streamable HTTP. Every request is independently authenticated, so requests can be served safely across restarts and multiple application replicas.

Authentication

There are two ways in.

API token. Include it in the Authorization header:

Authorization: Bearer orca_your_token_here

Tokens must have appropriate permissions for the tools you want to use. Each token is associated with a specific workspace; all operations are scoped to it.

OAuth. Clients that speak the MCP OAuth flow (Claude and ChatGPT connectors, for example) can point at https://app.tryorcha.com/mcp with no token at all. Orcha serves the discovery documents at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource, and the client sends you to a consent screen where you sign in, pick the workspace the connector runs against, and choose which of read, write, and delete it gets. Granted permissions are capped at your workspace role at consent time and re-checked on every request, so losing a role narrows the connector immediately.

Requests with an Origin header

The server validates the Origin header, as the MCP Streamable HTTP specification requires. Clients that send no Origin are unaffected, which covers the Claude and ChatGPT connectors, the CLI, and agent runtimes generally. When a client does send Origin, its value must match the deployment's own origin or one configured in MCP_ALLOWED_ORIGINS; anything else is rejected with 403.

MCP_ALLOWED_ORIGINS controls transport validation only. It does not enable CORS or allow direct cross-origin browser JavaScript to call /mcp.

Removed transport

The legacy SSE transport is gone. /mcp/sse and /mcp/message return 410 Gone with a pointer to POST /mcp rather than failing in a way that looks like an outage.

Client configuration

Client-specific walkthroughs: Claude Code, Claude Desktop, Codex, Cursor. The generic HTTP configuration is:

{
  "mcpServers": {
    "orcha": {
      "url": "https://app.tryorcha.com/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer orca_your_token_here"
      }
    }
  }
}

Codex is the exception: it takes TOML in ~/.codex/config.toml and does its own OAuth, so no token appears in the file.

[mcp_servers.orcha]
url = "https://app.tryorcha.com/mcp"
auth = "oauth"

Usage guides

Orcha ships its own guidance for agents, so a client does not have to infer how these tools fit together. The same content is served three ways:

• get_usage_guide tool, below. Works in every MCP client.
• skills/list and skills/get, under the draft io.modelcontextprotocol/skills extension. Skill files are addressed as skill://orcha/<name>/<path> and read through resources/read. Clients that do not implement the extension ignore it.
• The Claude Code plugin, which installs the same skills alongside the server connection. See Connect Claude Code.

The guides are retrieval (which tool answers which question, and how to tune search_context), citations (attribution and freshness), authoring (writing back safely), and troubleshooting (empty results, scope errors, and feedback).

get_usage_guide

Read one of Orcha's usage guides, or list what is available.

Returns: The guide body as markdown, or a JSON index of topics when called with no arguments. Permission: none; the guides carry no workspace content.

File and folder tools

list_files

List all files accessible to the token within the associated workspace.

Returns: Array of file objects (without content), each including workspaceId. Permission: read

get_file

Get a specific file including its content. For large files, pass fromLine/maxLines to read only the relevant range; search_context results include location.startLine anchors to jump from.

Returns: File content. Ranged reads are prefixed with a [lines X-Y of N] header. Permission: read

get_files

Get the contents of multiple files in one call. Prefer this over repeated get_file calls when the needed files are already known.

Returns: Array of file objects; missing or out-of-scope IDs return an error entry instead of failing the call. Permission: read

create_file

Create a new file in the token's associated workspace.

Returns: Created file object with workspaceId. Permission: write

update_file

Update an existing file's content.

Returns: Updated file object. Permission: write

delete_file

Move a file to trash (soft delete).

Returns: Success confirmation. Permission: delete

list_folders

List all folders accessible to the token within the associated workspace.

Returns: Array of folder objects, each including workspaceId. Permission: read

create_folder

Create a new folder in the token's associated workspace.

Returns: Created folder object with workspaceId. Permission: write

search_files

Search files by name within the token's workspace.

Returns: Array of matching file objects with workspaceId. Permission: read

list_source_documents

List read-only documents synced from connected sources (for example GitHub repositories). Source IDs come from get_workspace_overview, whose connectedSources section names each connected source with its document count and sync status. Synced documents are not files; read their content through search_context.

Returns: Array of source documents (id, sourceId, title, externalId, mimeType, indexStatus, lastSyncedAt). Permission: read (workspace-wide token; not available to folder-scoped tokens)

Context discovery and memory tools

Orcha tells connected agents to start with get_workspace_overview when they are unfamiliar with a workspace. The overview includes discoverable memories and connected sources. Agents can also call list_memories directly, compare each memory's useWhen guidance to the current task, and load a matching memory with get_memory.

Use memories for established workflows that need a complete, curated source set. A memory groups files, whole folders, connected-source documents, and database views; members resolve to their current contents at load time, and coverage notes report anything excluded, truncated, or unavailable. With write permission, agents curate them too: create_memory builds a set from files, folders, synced documents, and databases, and update_memory revises metadata or membership (member removal additionally requires the delete permission). Folder-scoped grants can only add members they can read: in-scope files, folders, and databases, never connected-source documents. Use search_context for open-ended or ad hoc questions where only the most relevant excerpts are needed.

search_context

search_context runs hybrid retrieval (PostgreSQL full-text + vector search fused with weighted reciprocal-rank fusion) over every indexed document in the workspace. The query supports websearch syntax: "quoted phrases" and -excluded terms.

Typed sub-queries broaden recall without hijacking the original ask (which always runs at double weight): lex entries carry exact keywords for full-text search, vec entries carry a natural-language restatement for vector search, and hyde entries carry a 30 to 80 word hypothetical answer passage that is embedded in place of the question.

mode controls upstream freshness cost. fast searches retained content only and never contacts a provider. balanced (the default) additionally searches the connected-source catalog — the bounded metadata inventory of objects whose bodies are not persistently indexed — and when a catalog entry decisively matches the ask, fetches up to a few bodies live from the provider, chunked in memory and cited with syncMode: "live". fresh also consults live-mode providers (for example issue trackers) directly. Every live call is metered against the connection's daily provider budget.

The response has two parts: results (cited evidence) and coverage (routing notes: what was fetched live, what the catalog lists but was not fetched, and budget or availability limits). Coverage notes are not evidence and must not be quoted as content.

Each result includes content, score, citation, the owning folder or source context, document updatedAt, and a location with startLine/endLine anchors plus the Markdown headingPath. Follow up with a ranged get_file instead of fetching whole files.

Example memory retrieval:

{
  "name": "get_memory",
  "arguments": {
    "slug": "engineering-onboarding"
  }
}

query_source

query_source queries exactly one connected source when the agent intentionally wants that provider rather than the whole workspace. It searches the source's retained content first, then its provider live-search path (for live-mode providers) or its catalog, fetching a small number of best-matching bodies live under the connection's daily provider budget. Folder-scoped tokens cannot use it.

The response mirrors search_context: results with citations plus coverage notes, and providerOperations reporting what the call spent upstream.

fetch_source_document

fetch_source_document returns one connected-source document's full body by sourceId and externalId (found in search_context coverage, list_source_documents, or query_source citations). Retained documents come from the index (origin: "indexed"); catalog-only documents are fetched live from the provider under the daily budget (origin: "live") and are not persisted. Folder-scoped tokens cannot use it.

browse_context

browse_context runs a restricted, read-only shell script against a virtual tree of the workspace: /files (files and folders), /memories (curated memories with useWhen READMEs), /databases (records rendered as markdown files), and /sources (connected sources with provider citations). A root README.md orients the agent; start with cat /README.md or ls /.

Supported commands: pwd, cd, ls [-l], tree [-L n], find [-name glob] [-type f|d] [-maxdepth n], cat [-n], grep/rg (-i, -n, -l, -r, -F), head/tail [-n N], wc, stat, and help, with | pipelines and ;/&& chaining. The script runs in Orcha's own parser; write-shaped constructs are rejected. Executions are bounded by a scan budget and an output cap, and responses append a citations block for every file whose content was returned. Use stat <path> for entity IDs, deep links, and freshness.

grep/rg patterns use RE2 syntax, which matches in time linear to the input so no pattern can stall a request. Constructs that require backtracking, notably lookahead, lookbehind, and backreferences, are not supported and return an error naming the unsupported construct. Pass -F to match the pattern literally. find -name takes a glob (*, ?), not a regular expression.

Use browse_context for structural exploration (what exists, where things live, exact-string greps) and search_context for ranked semantic retrieval.

{
  "name": "browse_context",
  "arguments": {
    "script": "tree -L 2 /files ; cat /memories/starter/README.md"
  }
}

Structured database tools

Database tools use stable database, property, and record UUIDs. Record values are objects keyed by property ID, and the API validates each value against its property type.

file_reference properties accept one file UUID or an array when the property enables multiple files. asset_reference properties identify imported binary attachments. Records may also expose a contentFileId page body. Referenced resources must be active and belong to the database workspace. Folder-scoped tokens cannot create out-of-scope file references, and inaccessible file references or page bodies are redacted from database query results.

Example query:

{
  "name": "query_database",
  "arguments": {
    "databaseId": "11111111-1111-4111-8111-111111111111",
    "search": "launch",
    "sortFieldId": "22222222-2222-4222-8222-222222222222",
    "sortDirection": "asc",
    "limit": 50
  }
}

Example record creation:

{
  "name": "create_database_record",
  "arguments": {
    "databaseId": "11111111-1111-4111-8111-111111111111",
    "values": {
      "22222222-2222-4222-8222-222222222222": "Launch",
      "33333333-3333-4333-8333-333333333333": true
    }
  }
}

Feedback tool

submit_feedback

Send feedback about the workspace's context to its maintainers: missing or stale content, wrong retrieval results, tool problems, or anything else worth fixing. Delivery reuses the product feedback pipeline (an email to the feedback inbox plus an internal notification); nothing is stored in the workspace.

Returns: A confirmation that the feedback was delivered. Permission: read

{
  "name": "submit_feedback",
  "arguments": {
    "message": "search_context returns the 2025 release runbook for 'deploy checklist'; the current one is not indexed.",
    "category": "stale_content",
    "context": { "query": "deploy checklist" }
  }
}

Token scoping

Tokens can be scoped to restrict MCP tool access:

When a token is folder-scoped:

• list_files and list_folders return only accessible items
• get_file returns 403 for out-of-scope files
• create_file requires the target folder to be in scope
• search_files only returns results within scope
• database tools only expose databases assigned to an accessible folder; root-level databases require a workspace-wide token

Example prompts

Once connected, you can ask your AI assistant:

Reading context:

• "What files do I have in Orcha?"
• "Show me the content of my architecture.md file"
• "Search for files related to API"
• "Check which Orcha memories apply to this task and use the best match"

Managing context:

• "Create a new file called project-notes.md with some starter content"
• "Update my config.json with the new settings"
• "Organize my files into a Projects folder"

Using context:

• "Read my brand-voice.md and use that style to write a blog post"
• "Check my api-spec.json and generate TypeScript types"
• "List the records in my Projects database that mention launch"

Error handling

MCP tool calls may return errors in the following cases:

Errors are returned as tool call errors with descriptive messages.

Tool calls share the per-token rate limits documented in the API reference. Exceeding a window is answered at the transport level with HTTP 429 and a Retry-After header rather than as a tool error. Protocol traffic such as initialize and tools/list does not count against the limits, so a handshake never costs quota. Each metered message in a JSON-RPC batch counts individually.