MCP connections

MCP exposes external tools to an Agent. Rebyte initializes the configured servers, discovers their tools, applies any allowlist, and records execution as mcp_call Items.

Configure an HTTP server

const agent = await client.beta.agents.create({
  model: 'gpt-5.6-luna',
  tools: [{
    type: 'mcp',
    server_label: 'company',
    required: true,
    connection_origin: 'service',
    transport: {
      type: 'http',
      server_url: 'https://mcp.example.com/mcp',
    },
  }],
});

Replace the URL with your server. Service-origin HTTP connections use public HTTPS endpoints. An environment-origin connection runs inside the Session VM and follows its network policy.

Add authentication

Use Session-level transport.authorization or transport.headers for inline HTTP authentication. These values are encrypted and omitted from public Session resources.

For reusable credentials, create a Vault and include its ID in the Session's vault_ids. Vault authentication applies to service-origin HTTP connections. It does not reuse old UI connector installations.

Saved Agents store reusable MCP configuration, not inline HTTP secrets. Supplying Session agent.tools replaces the entire saved list, so include every tool the Session needs.

For example, using the saved agent above and a token authorized by your server:

const definitions = agent.tools;
const session = await client.beta.agents.sessions.create({
  agent_id: agent.id,
  agent: { tools: definitions.map(tool => tool.type === 'mcp' &&
    tool.server_label === 'company' && tool.transport.type === 'http'
    ? { ...tool, transport: { ...tool.transport, authorization: `Bearer ${accessToken}` } }
    : tool) },
  input: 'Use the company tools to answer my question.',
});

This Session has no Sandbox. Authentication is bound to this Session; it is not copied into the saved Agent or reused from the product UI's connector installation.

Use stdio

Stdio MCP servers run inside the Session's managed environment. Omit connection_origin in stdio creation requests; the server derives the environment origin. Prepare their binaries and dependencies during setup. transport.env_vars selects Session environment variables; inline transport.env is also supported for hosted stdio. Those values are visible to code running in that VM.

Stdio connections preserve process state across model turns and pause/resume. A dead established process fails explicitly instead of silently restarting with new state. Hosted stdio currently requires enabled network access.

Control tools and failures

Use allowed_tools to limit discovered tools. request_metadata is passed as MCP request metadata. If a required server cannot initialize, the Turn fails. An unavailable optional server supplies no tools and allows the Turn to continue.

Current transport support covers Streamable HTTP request/response (including POST SSE), GET SSE for service and environment HTTP connections, and stdio tool calls. Deleting a Session terminates its initialized HTTP connections upstream before removing the Sandbox; a provider 404 or 405 on that termination is treated as already handled. GET event-ID replay across a detached and reconnecting client is not implemented — a fresh GET stream does not replay notifications sent while disconnected. MCP image output is currently serialized into model history rather than handled as image content.

Resource discovery

Configured MCP connections also expose list_mcp_resources, list_mcp_resource_templates and read_mcp_resource to the model. They enumerate or read the connected server's resources, using the same Session-scoped connection and identity. They do not grant access to unconfigured servers. These are runtime helpers, not client functions your application must execute.

GET SSE is the upstream MCP server's notification stream. It is separate from Rebyte's Session event stream. A server's transport/capability support determines whether it supplies that stream; it is not another model execution or Sandbox.