Connect agents outside a desktop client

Native memory and project files such as CLAUDE.md stay inside one client. Claude Code reads CLAUDE.md from the repository where it runs. The built-in memory of an assistant stays with the account of that assistant.

Other agents do not have these files or this memory. Examples are an agent that you build with the Claude API, an agent on a server schedule, an agent in a workflow tool, and an agent that you message over text. At the start of each run, such an agent does not know your decisions, conventions, or source documents. It knows them only if you send them.

Orcha gives this knowledge through one endpoint that all runtimes can call. The agent reads the same workspace that you use in the web app and in Claude Code. It has the permissions of the token or OAuth grant that you give it.

Each search_context result has a citation, a document updatedAt, and line anchors. Thus, the agent can tell where an answer came from and how current it is. A folder-scoped, read-only token limits a cloud agent to the part of the workspace that it needs.

This guide shows six runtimes. At the end of each section, a check confirms that the agent gets a result with a citation.

Prerequisites

• A workspace with content. First, add files, import a vault, or connect a source. Refer to the quickstart and Connect a source.
• A credential. Most runtimes in this guide run without a person at a browser. Thus, they use an API token from the API Tokens page. The token starts with orca_. It is bound to the workspace that you viewed when you created it. Orcha shows the token only one time. Runtimes that run the MCP OAuth flow can use a consent-screen grant instead. In this guide, OpenClaw is such a runtime. On the consent screen, you select the workspace and the permissions.
• The narrowest scope that works. For an agent that only answers questions, give read only. Add write only if the agent must create files, records, or memories. To keep the agent in one part of the workspace, limit the token to specified folders. Folder-scoped tokens exclude root-level files and root-level databases. They cannot use the connected-source tools (query_source, fetch_source_document, list_source_documents). Refer to Tokens and scoping.
• A secret store. Put the token in an environment variable or in the secret manager of your platform. The examples read the token from ORCHA_TOKEN.

Two endpoints give access to the same workspace:

If the runtime has an MCP client, use MCP. If the runtime can only send HTTP requests, use REST.

Claude Messages API (MCP connector)

For a cloud agent, the MCP connector is the shortest method. The Anthropic servers open the MCP connection to Orcha. Thus, your code makes one API call and does not run an MCP client. The connector supports only MCP tool calls. All Orcha tools are MCP tool calls.

1. Install the Anthropic SDK with pip install anthropic.
2. Export your Anthropic API key as ANTHROPIC_API_KEY.
3. Export your Orcha token as ORCHA_TOKEN.
4. Run the script below.

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 find our deployment requirements. "
            "Cite the source of each requirement.",
        }
    ],
)
 
for block in response.content:
    if block.type == "mcp_tool_use":
        print("tool call:", block.name, block.input)
    elif block.type == "mcp_tool_result":
        print("tool result:", block.content)
    elif block.type == "text":
        print(block.text)

The request must have both parts. Each server in mcp_servers must have exactly one mcp_toolset entry in tools with the same mcp_server_name. If it does not, the request fails validation. The connector sends authorization_token to Orcha as a bearer token. Orcha accepts an orca_ token in this field.

You can give the agent only the read tools that it needs. To do this, disable all tools by default and enable each tool by its name:

{
  "type": "mcp_toolset",
  "mcp_server_name": "orcha",
  "default_config": { "enabled": false },
  "configs": {
    "get_workspace_overview": { "enabled": true },
    "search_context": { "enabled": true },
    "get_file": { "enabled": true }
  }
}

Verify: The output contains a tool call: search_context line. The mcp_tool_result content includes a citation for each result. If the model answers without a tool call, add "Use the Orcha tools" to the prompt.

Claude Agent SDK

The Agent SDK runs the Claude Code agent loop in your own process or container. Give Orcha as a remote HTTP server in the mcpServers option (mcp_servers in Python). The SDK does not open a browser and does not run an interactive OAuth flow. Thus, send the token in headers.

The agent can call MCP tools only after you give explicit permission. To allow the Orcha tools, use the mcp__orcha__* wildcard. The permissions of the token still set the limit for each call.

TypeScript

1. Install the SDK with npm install @anthropic-ai/claude-agent-sdk.
2. Export ORCHA_TOKEN and your Anthropic credentials.
3. Run the script below.

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt:
    "Search Orcha for our deployment requirements and cite the source of each one.",
  options: {
    mcpServers: {
      orcha: {
        type: "http",
        url: "https://app.tryorcha.com/mcp",
        headers: {
          Authorization: `Bearer ${process.env.ORCHA_TOKEN}`,
        },
      },
    },
    allowedTools: ["mcp__orcha__*"],
  },
})) {
  if (message.type === "system" && message.subtype === "init") {
    console.log("MCP servers:", message.mcp_servers);
  }
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Python

1. Install the SDK with pip install claude-agent-sdk.
2. Export ORCHA_TOKEN and your Anthropic credentials.
3. Run the script below.

import asyncio
import os
 
from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, SystemMessage, query
 
 
async def main():
    options = ClaudeAgentOptions(
        mcp_servers={
            "orcha": {
                "type": "http",
                "url": "https://app.tryorcha.com/mcp",
                "headers": {"Authorization": f"Bearer {os.environ['ORCHA_TOKEN']}"},
            }
        },
        allowed_tools=["mcp__orcha__*"],
    )
 
    async for message in query(
        prompt="Search Orcha for our deployment requirements and cite the source of each one.",
        options=options,
    ):
        if isinstance(message, SystemMessage) and message.subtype == "init":
            print("MCP servers:", message.data.get("mcp_servers"))
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)
 
 
asyncio.run(main())

Use "type": "http" for Orcha. Orcha supports only Streamable HTTP. The legacy SSE paths return 410 Gone.

Verify: The MCP servers: line shows orcha with the status connected. The status can also be pending when the SDK has a cached tool list. The final result gives the names of the documents that the agent used.

If the status is failed or needs-auth, do not trust the answer. Examine the token first. When a server is not available, the agent can use its built-in tools instead.

Claude Managed Agents

Managed Agents run the agent loop and a sandbox for each session on the Anthropic infrastructure. They support remote MCP servers. The configuration has two parts:

• The agent declares the Orcha server without credentials.
• A vault keeps the token and supplies it when a session starts.

The token does not go into the sandbox.

1. Create a vault for the credentials of the agent.
2. Add the Orcha token to the vault as a static_bearer credential. Its mcp_server_url must be the same as the server URL on the agent.
3. Create an environment. With limited networking, set allow_mcp_servers to true. If you do not, session creation fails with a 400.
4. Create the agent with Orcha in mcp_servers and a matching mcp_toolset.
5. Start a session with the vault in vault_ids.
6. Send a message.
7. Read the event stream.

import os
 
import anthropic
 
client = anthropic.Anthropic()
 
# One-time setup. Store the IDs and reuse them for every session.
vault = client.beta.vaults.create(display_name="Orcha research agent")
client.beta.vaults.credentials.create(
    vault_id=vault.id,
    display_name="Orcha read-only token",
    auth={
        "type": "static_bearer",
        "mcp_server_url": "https://app.tryorcha.com/mcp",
        "token": os.environ["ORCHA_TOKEN"],
    },
)
 
environment = client.beta.environments.create(
    name="orcha-research",
    config={
        "type": "cloud",
        "networking": {"type": "limited", "allow_mcp_servers": True},
    },
)
 
agent = client.beta.agents.create(
    name="Orcha research agent",
    model="claude-opus-5-5",
    system="Answer from the Orcha workspace. Cite the source of every claim.",
    mcp_servers=[
        {"type": "url", "name": "orcha", "url": "https://app.tryorcha.com/mcp"},
    ],
    tools=[
        {"type": "agent_toolset_20260401"},
        {
            "type": "mcp_toolset",
            "mcp_server_name": "orcha",
            # The token is read-only, so Orcha calls run without a per-call approval.
            "default_config": {"permission_policy": {"type": "always_allow"}},
        },
    ],
)
 
# Every run.
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)
 
with client.beta.sessions.events.stream(session_id=session.id) as stream:
    client.beta.sessions.events.send(
        session_id=session.id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {
                        "type": "text",
                        "text": "Search Orcha for our deployment requirements and cite each source.",
                    }
                ],
            }
        ],
    )
    for event in stream:
        if event.type == "agent.mcp_tool_use":
            print("Orcha tool call:", event)
        elif event.type == "agent.message":
            for block in event.content:
                if block.type == "text":
                    print(block.text, end="", flush=True)
        elif event.type == "session.error":
            print("session error:", event)
        elif event.type in ("session.status_idle", "session.status_terminated"):
            break

By default, an MCP toolset uses the always_ask permission policy. With this policy, the session stops before each Orcha call until you approve the call. The example sets always_allow because the token is read-only.

If you give the agent a token with write or delete, keep always_ask for the write tools. Alternatively, use the auto policy.

Verify: The stream prints an Orcha tool call: line for a search_context call. Then it prints an answer that gives the names of its sources.

If Orcha rejects the credential, the session still starts. It then sends a session.error event with mcp_authentication_failed_error. Make sure that the mcp_server_url of the vault credential is exactly https://app.tryorcha.com/mcp.

n8n

n8n agents connect to MCP servers through the MCP Client Tool node. You attach this node to an AI Agent node as a tool.

1. Open the workflow that contains your AI Agent node.
2. From the nodes panel, add an MCP Client Tool node.
3. Connect the node to the tool input of the agent.
4. Set Server Transport to HTTP Streamable.
5. Set Endpoint to https://app.tryorcha.com/mcp.
6. Set Authentication to Bearer Auth.
7. Create a Bearer Auth credential with your orca_ token as the value.
8. Set Tools to Include to Selected.
9. Select get_workspace_overview, search_context, and get_file.

The node can show one SSE Endpoint field and no Server Transport option. In this condition, the workflow uses version 1 of the node, which supports only SSE. Orcha has no SSE transport. To get the current version, delete the node and add it again from the nodes panel.

If an MCP client is not available, call the REST endpoint from an HTTP Request node. Use these settings:

• Method: POST.
• URL: https://app.tryorcha.com/api/v1/search_context.
• Authentication: Bearer Auth with the same token.
• Body: JSON, for example {"query": "deployment requirements", "limit": 5}.

Verify: Run the workflow with the message "Search Orcha for our deployment requirements and cite each source." In the execution log, the MCP Client Tool node shows a search_context call. Its output includes a citation for each result.

Manus

Manus connects to remote MCP servers as custom connectors.

1. In Manus, open Settings.
2. Open Integrations.
3. Open Custom MCP Servers.
4. Click Add Server.
5. Type Orcha as the server name.
6. Type https://app.tryorcha.com/mcp as the server URL.
7. Type your orca_ token as the bearer token.
8. Save the server. Manus then tests the connection.

Manus also shows a Connectors screen with Add MCP by URL. Both screens use the same URL.

Verify: After the connection test, Manus shows the list of Orcha tools. Ask "Search Orcha for our deployment requirements and cite each source." Make sure that the task log shows a search_context call.

OpenClaw

OpenClaw is a self-hosted personal agent. It keeps MCP server definitions under mcp.servers in its configuration. It supports Streamable HTTP and the MCP OAuth flow, and Orcha supports both. The OAuth grant uses the workspace and the permissions that you select on the Orcha consent screen.

Stop the local Gateway before you start. The add and login commands do not work while the Gateway runs.

1. Stop the local Gateway.

2. Add the Orcha server:

   openclaw mcp add orcha \
     --url https://app.tryorcha.com/mcp \
     --transport streamable-http \
     --auth oauth

3. Run openclaw mcp login orcha.

4. Open the authorization URL that the command prints.

5. On the Orcha consent screen, select the workspace.

6. Give read.

7. Run openclaw mcp doctor orcha --probe. This command confirms the connection and shows the list of tools.

8. Start the Gateway again.

To give access to only some tools, add --include 'get_workspace_overview,search_context,get_file' to the add command. Alternatively, set toolFilter.include on the server in the configuration.

Verify: doctor --probe shows the Orcha tools. Then ask your agent "Search Orcha for our deployment requirements and cite each source." Make sure that the reply gives the names of the source documents.

Meta Muse

Muse is the personal agent from Meta. It runs on its own cloud computer, so it can connect to the hosted Orcha endpoint.

Meta documents a Custom Connector for services that are not in the Muse connector list. You tell Muse to create one. Muse keeps the credential in its secure credential store. The Meta documentation does not give the protocol of a custom connector. Thus, these steps give Muse both the MCP endpoint and the REST endpoint.

1. Create an Orcha token with read only.
2. Limit the token to the folders that Muse needs.
3. In a Muse chat, tell Muse to create a custom connector for Orcha.
4. Give Muse the MCP endpoint https://app.tryorcha.com/mcp.
5. Give Muse the header Authorization: Bearer orca_... with your token.
6. If Muse asks for an API instead, give it POST https://app.tryorcha.com/api/v1/search_context. Use the same header and a JSON body that contains query.

Meta does not review custom connectors. A read-only, folder-scoped token keeps the access of Muse small. You can revoke the token at any time on the API Tokens page.

Verify: Ask Muse "Search Orcha for our deployment requirements and tell me which documents you used." The answer gives the names of Orcha documents. On the Orcha API Tokens page, the Last used date of the token is today.

What the agent can and cannot do

The token or grant sets what an agent can do. The runtime does not change this.

• Read. With read, the agent can search, browse, and read these items: files, folders, databases, memories, and indexed connected-source documents. Tell an agent that does not know the workspace to start with get_workspace_overview. Then tell it to use search_context.

• Connected sources are read-only. Orcha indexes them from the provider. An agent can query and fetch them, but it cannot change them. Synced documents are not files. query_source and fetch_source_document need a workspace-wide token. Live fetches count against the daily provider budget of the connection.

• Memories. With write, the agent can create a memory with create_memory. It can change a memory with update_memory. To remove a member, the agent also needs delete. Folder-scoped grants can add only files, folders, and databases in their scope. They can never add connected-source documents.

• Files and records. With write, the agent can create and update files, folders, and database records. With delete, it can move them to trash.

• Rate limits. Each MCP tool call and each /api/v1 request counts against windows for each token. The windows are one minute, one hour, and one day. The limits per minute are:

  • 600 requests on Free.
  • 1,200 requests on Starter.
  • 2,400 requests on Studio and Team.
  • 6,000 requests on Pro and Business.

  Protocol traffic, such as initialize and tools/list, does not count. When a window has no requests left, Orcha returns 429 with a Retry-After header. Refer to Rate limits.

• Feedback. All agents with read can call submit_feedback. This tool reports missing or old context to the workspace maintainers.

Troubleshooting

Orcha supplies a troubleshooting usage guide. It gives information about empty results, scope errors, and feedback. To read it, a connected agent calls the get_usage_guide tool with topic set to troubleshooting. The MCP reference gives the list of error types.

If the problem continues, refer to Support.