Quickstart

On this page, you ask one question from two locations. One location is a desktop AI client. The other location is an agent that runs on a different computer. Both answers cite the same Orcha file. This shared citation is the purpose of Orcha. All of your tools read the same context and can show the source of an answer.

You do not need an API token before step 4. In step 4, you need a token only if your agent uses a bearer token.

1. Sign up

Sign up at app.tryorcha.com with email and password, Google, or GitHub. Orcha creates your organization and first workspace for you. All content that you add belongs to a workspace. The workspace switcher in the sidebar shows your current workspace.

After the first sign-in, a new account opens the setup wizard. Click Continue to go through the steps, and click Finish on the last step. Or, click Skip to skip one step, or click Skip setup at the top right to go directly to the app. You can do all of the steps on this page without the wizard.

2. Bring in your content

Default: import an Obsidian vault or a Notion export.

1. Make a ZIP file of your Obsidian vault folder. Or, download the Notion Markdown and CSV export. Notion gives this export as a ZIP file.
2. Open the account menu at the bottom left of the sidebar. Then click Import.
3. Upload the archive.
4. Examine the preview. It shows the items that the import will create.
5. Start the import.

The import puts the content into your current workspace. The workspace switcher in the sidebar shows this workspace. To import into a different workspace, select that workspace in the switcher before you start.

The import keeps folder hierarchy, relations, attachments, and links. For conflict policies, limits, and rollback, see Import from Obsidian and Notion.

Alternative: connect one source. Use this option if your knowledge is in GitHub, Google Drive, Notion, Dropbox, Linear, or a different provider.

1. Open Connectors.
2. Select the provider.
3. Select what Orcha indexes.

Orcha makes a catalog of the source first. Then it indexes only the items that you select. See Connect a source.

Before you continue, select one file that you know well, for example a decision record or a project brief. Write down a question that the file answers. You ask this question in step 5.

3. Connect a desktop client

Desktop clients connect to https://app.tryorcha.com/mcp over OAuth. You do not copy a token. The client opens the Orcha sign-in page. On the consent screen, you select the workspace. You also select the permissions that the connection gets: read, write, and delete. For this quickstart, read is sufficient.

• Claude Code: Install the Orcha plugin. First, run /plugin marketplace add westonhancock/orcha-mcp. Then run /plugin install orcha@orcha. Claude Code starts the OAuth flow on first use. See Connect Claude Code.
• Claude Desktop: Add Orcha as a custom connector with the URL https://app.tryorcha.com/mcp. When the client asks, sign in. See Connect Claude Desktop.
• ChatGPT: Install the Orcha plugin. Or, add a custom connector with the same URL. See Connect ChatGPT.
• Cursor: Add the server URL to your MCP settings. When Cursor asks, sign in. See Connect Cursor.

To test the connection, ask the client "What is in my Orcha workspace?" The client must call get_workspace_overview and describe the content that you imported.

4. Connect an agent that runs outside the client

Connect an agent that does not run on your desktop. Examples are a script that calls the Claude API, a scheduled job, a workflow tool such as n8n, or a personal agent. This agent reads the same workspace.

Most of these runtimes operate without a person at a browser. Thus, they authenticate with an API token, not with OAuth.

1. Open the account menu at the bottom left of the sidebar. Then click API Tokens.
2. Create a token with read permission only.
3. Copy the token into a secret store or an environment variable immediately. Orcha shows the token only one time.

The token starts with orca_. It is bound to the workspace that you view when you create it. To limit the token to specific folders, see Tokens and scoping. Some runtimes, such as OpenClaw, use the MCP OAuth flow. These runtimes do not need a token. They use the consent screen.

The shortest procedure uses the Claude Messages API with the MCP connector. In this procedure, the Anthropic servers open the MCP connection for you.

1. Install the SDK with pip install anthropic.
2. Export ANTHROPIC_API_KEY and ORCHA_TOKEN.
3. Run this script:

import os
 
import anthropic
 
client = anthropic.Anthropic()
 
response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://app.tryorcha.com/mcp",
            "name": "orcha",
            "authorization_token": os.environ["ORCHA_TOKEN"],
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "orcha"}],
    messages=[
        {
            "role": "user",
            "content": "Use search_context to answer: <your question>. "
            "Cite the Orcha file each part of the answer comes from.",
        }
    ],
)
 
for block in response.content:
    if block.type == "text":
        print(block.text)

Replace <your question> with the question from step 2. For the Claude Agent SDK, Claude Managed Agents, n8n, Manus, OpenClaw, and Meta Muse, see Connect agents outside a desktop client.

5. Ask the same question from both

1. Ask the question from step 2 in your desktop client. Add "Cite the Orcha file you used."
2. Run the agent from step 4 with the same question.
3. Compare the two answers.

Both answers must name the same Orcha file as their source. The Orcha search_context tool returns a list of results. Each result has these fields:

• citation identifies the source: citation.title, citation.provider, and citation.deepLink, the link that opens the file. For an Orcha file, citation.location and citation.version are usually null.
• updatedAt is the time of the last change to the document.
• location.startLine and location.endLine are the line anchors of the chunk. They are on the result, not on the citation.

Thus, each answer can point to the exact lines that it used. ChatGPT in standard mode cites the link that its search and fetch tools return. This link opens the same file.

If the answers cite different files or no file:

• Tell the client to "use the Orcha tools". Then the client searches and does not answer from its own memory.
• Make sure that the desktop connection and the token use the same workspace.
• Wait a few minutes after a new import or a new connected source. Orcha needs this time to complete the indexing.
• Make sure that the token has access to the folder of the file. A folder-scoped token can exclude the file.

Retrieval explains how ranking and citations work. Effective search shows how to write questions that give good retrieval results.

Use the REST API

All of the functions on this page are also available over HTTP under /api/v1 with the same orca_ token. To list files:

curl -H "Authorization: Bearer $ORCHA_TOKEN" \
  https://app.tryorcha.com/api/v1/files

To create a file:

curl -X POST \
  -H "Authorization: Bearer $ORCHA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "example.md", "content": "# Example", "fileType": "markdown"}' \
  https://app.tryorcha.com/api/v1/files

To search with citations, send the query to search_context:

curl -X POST \
  -H "Authorization: Bearer $ORCHA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "deployment requirements", "limit": 5}' \
  https://app.tryorcha.com/api/v1/search_context

The REST response has the same results list as the MCP tool, with one difference. Each result has citation and updatedAt, but the line anchors are in metadata.startLine and metadata.endLine. The REST response has no location field.

The API reference documents all endpoints. The MCP reference lists all MCP tools.