# MCP connections

Connect OrchaJS agents and subagents to MCP servers across Node.js, browsers, Expo, and React Native.

Source: https://orcha.sh/docs/mcp
Markdown: https://orcha.sh/docs/mcp.mdx

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

```ts
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 HTTP

Create `orcha/mcp/github/index.json`:

```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 stdio

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

```json
{
  "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 behavior

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.

## Credentials

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.