MCP connections

MCP connections are assigned directly to each agent or subagent. Every tool advertised by an assigned server becomes available to that agent.

orcha.init({
  providers: {
    anthropic: process.env.ANTHROPIC_API_KEY ?? "",
  },
  mcp: {
    credentials: {
      GITHUB_MCP_TOKEN: process.env.GITHUB_MCP_TOKEN,
    },
  },
  agents: {
    supportAgent: {
      path: "./supportAgent",
      mcp: {
        github: "./mcp/github",
      },
      subagents: {
        researcher: {
          path: "./researcher",
          mcp: {
            docs: "./mcp/docs",
          },
        },
      },
    },
  },
});

Connections are not inherited. A subagent has access only to the MCP folders listed in its own registration.

Streamable HTTPCopy Anchor Link

Create orcha/mcp/github/index.json:

{
  "transport": "streamable-http",
  "url": "https://mcp.example.com",
  "headers": {
    "Authorization": "Bearer ${GITHUB_MCP_TOKEN}"
  },
  "timeoutMs": 30000,
  "maxOutputBytes": 1000000
}

Streamable HTTP is supported by Node.js, browser, Expo, and React Native targets. Browser and mobile applications must satisfy the MCP server's CORS policy and provide credentials securely at runtime.

Node.js stdioCopy Anchor Link

Local subprocess connections are available only for Node.js targets:

{
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@example/mcp-server"],
  "env": {
    "API_TOKEN": "${EXAMPLE_MCP_TOKEN}"
  }
}

Browser and React Native compilation rejects stdio connections because those platforms cannot launch subprocesses.

Tool behaviorCopy Anchor Link

Orcha connects lazily and discovers tools when an agent runs. Tools are namespaced as <connection>__<tool>, such as github__get_issue, preventing different MCP servers from colliding.

Calls and results are persisted as durable action events with MCP source metadata. MCP output is untrusted external data and has a configurable size limit.

The optional MCP SDK is installed automatically only when a registered agent uses MCP. Projects without MCP do not install or bundle it.

CredentialsCopy Anchor Link

Use ${NAME} placeholders in HTTP headers and stdio environment values. Node.js resolves placeholders from process.env; every runtime can resolve them from orcha.init().mcp.credentials.

Never place secret values directly in an MCP index.json. In browser and mobile applications, provide only user-scoped credentials that are safe for that client. Keep service credentials on a server-side Orcha runtime.