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-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.

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 credentials, create a Vault and include its ID in the Session's vault_ids. Vault authentication applies to service-origin HTTP connections. 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 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.

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.