MCP connections

MCP exposes external tools to an Agent. Rebyte discovers tools on demand from the explicitly configured servers, applies any allowlist, and records execution as mcp_call Items.

Reuse a connected account

To use an account already connected in Rebyte, add it to your API Agent from Platform → Agents → Configuration → Connections. The platform manages its authentication, including supported OAuth refresh. See the dedicated Platform connections guide for setup, account permissions, and Session behavior.

The HTTP and stdio configuration below is for servers you configure directly through the API.

Configure an HTTP server

const agent = await client.beta.agents.create({
  model: 'gpt-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.

Search and call MCP tools

Configured MCP servers automatically give the model search_tools and call_tool. Their entire tool catalogs are not placed in the initial model context. You do not add tool_search or defer_loading to an MCP entry; those settings are for client functions.

The model can search:

{"query":"warehouse stock","server":"company","limit":5}

search_tools accepts exactly one of query (BM25 text matching, up to 500 characters) or pattern (case-insensitive JavaScript regex, up to 200 characters). server optionally narrows the search to one configured label. limit defaults to 5 and is capped at 20. Regex execution has a 500 ms deadline. No embeddings or extra model are used for ranking.

Results include the server label, original tool name, description, and inputSchema. After inspecting the schema, the model calls call_tool, for example:

{"server":"company","name":"get_inventory","arguments":{"sku":"SKU42"}}

Rebyte executes the call on the MCP server. Your application does not execute these calls or submit function results. A known, authorized tool can also be called without searching first. call_tool cannot invoke client functions or Sandbox built-ins.

Catalog freshness and isolation

Rebyte caches paginated tools/list metadata for 30 seconds, scoped to the organization, Session, server configuration and effective credentials. Cache hits do not extend expiry. Received tools/list_changed notifications invalidate the entry; without a notification, search results can remain stale until expiry. Credentials and tool execution results are not stored in this cache.

Every actual tool call re-fetches the selected server's catalog, checks the current allowlist, and validates arguments against the current schema. A search result grants no authorization. Removed or forbidden tools fail explicitly; the MCP server remains authoritative at execution time.

Service-origin MCP search and calls need no Sandbox. Environment-origin MCP goes through the Session's lazy Sandbox initialization guard when used. These behaviors apply to API Agents; product UI Agent connectors keep their existing behavior.

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 service-origin HTTP credentials, create a Vault with static_bearer or mcp_oauth authentication and include its ID in the Session's vault_ids. A Vault does not automatically reuse accounts connected in Platform; use Platform connections to explicitly attach one.

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. This example supplies its own token; it does not use a Platform connection.

Use stdio

Stdio MCP servers run inside the Session's attached Environment. In the shared Environment API, other Sessions on that Sandbox can access its files, processes and visible secrets; separate MCP configuration does not provide VM isolation. Omit connection_origin in stdio creation requests; the server derives the environment origin. Prepare their binaries and dependencies during setup. transport.env_vars selects the attached Environment's variables; inline transport.env is also supported for hosted stdio. Those values are visible to code running in that VM.

Rebyte extension, available from October 12, 2026: transport.env_vars can also select a sandbox_environment credential explicitly bound through Session environment.vault_credentials. This sends its actual value to the stdio process. It does not use the HTTP MCP credential_id selector. Rotation affects new launches; an already-started stdio server keeps its original environment. See Vault delegation for the complete flow and current availability.

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.

Names in a shared Environment

With explicit sharing, environment-origin MCP brokers use server_label within the Sandbox. A later Session with the same label reuses the running broker and its launch configuration, even if that Session supplies different command, environment or HTTP settings. Conflicts are not compared or rejected, and simultaneous first launches have no guaranteed winner. The developer manages names and configuration consistency; use distinct labels for distinct services. This applies to stdio and environment-origin HTTP, not service-origin HTTP.

Deleting a Session can leave its stdio process alive in the shared Environment. HTTP MCP deletion still attempts upstream termination and can affect peers reusing that connection. Manage these effects in your application. See MCP names and reuse for examples and cleanup behavior.

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. Private Environment deletion also removes its Sandbox; a shared Environment with explicit sharing remains attached to other Sessions. During HTTP connection termination, a provider 404 or 405 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 resources through the Session's configured connection. In a shared Environment, a reused broker can serve an earlier launch configuration as described above. These helpers do not add another server connection. They 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.

Combine MCP calls in a Dynamic Workflow

Add { type: "dynamic_workflow" } alongside the MCP definitions to let generated JavaScript discover, call and combine their tools. The same Session credentials, server allowlists and argument validation apply. Nested calls return to the program rather than producing separate public MCP Items in this version. See Dynamic Workflow for an example and current availability.