Skip to main content

​
BYO MCP servers for AI agents

Orbit agents can discover and execute tools hosted on your own infrastructure or third-party platforms via the Model Context Protocol (MCP). Instead of writing and deploying individual webhooks for every capability, you can register an external MCP server once. Orbit’s execution engine queries the server’s tool catalog, binds callable functions directly to the agent’s tool registry at inference time, and manages transport and authentication automatically.

​
What MCP is

The Model Context Protocol (MCP) is an open standard that standardizes how artificial intelligence agents discover and invoke capabilities exposed by external servers. Rather than hard-coding separate API clients or webhook formats for each capability, an MCP server publishes a machine-readable tool catalog through a standardized JSON-RPC interface. When an agent needs to perform an action—such as checking inventory, querying an internal database, or dispatching an external ticket—it queries the server’s catalog, inspects the parameter schemas, and issues structured tool calls across standard transports.

​
Runtime tool discovery and execution

When an agent execution begins, Orbit loads all enabled MCP servers registered to that agent. The agent runtime calls registerBYOMcpTools(), issuing a JSON-RPC tools/list handshake against each registered server URL:
  1. Discovery handshake: Orbit connects to the registered server URL (using HTTP with Server-Sent Events or Streamable HTTP) and calls tools/list.
  2. Schema inspection: The remote server returns its tool definitions, parameter schemas, and descriptions.
  3. Registry injection: Orbit wraps each discovered method in an execution adapter and injects it into the agent’s active ToolRegistry alongside built-in platform tools.
  4. Tool execution: When the LLM generates a tool call targeting a BYO tool, Orbit forwards the arguments via tools/call to the remote server, captures the result, and feeds it back into the model’s conversation context.
Discovered tool definitions are cached per server URL and credential pair to maintain fast turn latency, while dynamic health probes ensure broken endpoints are flagged in the operator console.

​
Scope and role gates

Registering and managing external MCP servers is protected by role-based access control and workspace isolation:
  • Role gates: Creating, updating, or deleting an MCP server registration requires an Owner, Admin, or Developer organization role. Read-only members and operators cannot modify server connections or alter credential bindings.
  • Workspace isolation: Every registered server is bound strictly to the tenant’s isolated schema and the specific agent ID. Server credentials and endpoints registered in one tenant cannot be discovered, queried, or accessed by any other workspace.
  • Write-time SSRF guards: When registering a server URL or OAuth2 token URL, Orbit’s network security layer resolves DNS and validates the destination. Registrations pointing to private IP blocks (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, 169.254.0.0/16), local aliases, or non-HTTPS schemes are rejected at registration time.

​
BYO MCP servers vs Tenant Custom Tools

Orbit offers two distinct mechanisms for extending agent capabilities with external code. Choosing the right mechanism depends on whether you are exposing a single bespoke endpoint or an entire operational catalog: If you already operate an internal service with a single action, a Tenant Custom Tool provides a lightweight webhook target. When integrating rich services with multiple commands, registering an MCP server avoids maintaining multiple individual tool schemas.

​
Relationship to Orbit-as-MCP (Hosted Server)

Orbit supports MCP in two distinct directions:
  • BYO MCP servers (Outbound, this page): Your Orbit AI agents act as the client. Orbit reaches out to your external MCP servers to discover and invoke third-party tools.
  • Hosted MCP server (Inbound): Orbit acts as the server. External clients (such as Claude Desktop, Cursor, or external orchestrators) connect to POST /api/v1/mcp to operate your Orbit workspace through platform tools like send_sms, place_call, or list_campaigns. For details on the hosted server, see Hosted MCP server.

​
See also