​

Register BYO MCP servers in the console

​

Prerequisites

• An Owner, Admin, or Developer role in your Orbit organization.
• A running MCP server accessible over public HTTPS.
• Authentication credentials for the server (either a static Bearer token or OAuth2 client credentials).

​

Step 1: Open the agent’s MCP servers tab

1. Navigate to Agents in the Orbit dashboard.
2. Select the agent you want to configure.
3. Open the Tools tab on the agent detail page, or navigate directly to /agents/<agent-id>?tab=tools.
4. In the tools view, locate the MCP Servers section.

​

Step 2: Register a new MCP server

1. Server name: Enter a unique identifier for the server (for example, customer-crm-tools). Names must be unique per agent.
2. Server URL: Enter the public HTTPS endpoint of your MCP server (for example, https://mcp.example.com/sse).
3. Authentication: Choose between:
   • None: If your server is open or network-gated.
   • Bearer token: Provide a static API token or bearer secret.
   • OAuth2: Select the grant type (client_credentials or refresh_token), then provide the Token URL, Client ID, Client Secret, and optional Scopes.
4. Test connection: Click Test connection before saving. Orbit issues an ephemeral probe against the endpoint to verify protocol compatibility and authentication without saving bad configurations.
5. Click Register server to save.

​

Step 3: Manage and delete registered servers

• Health and status: Orbit checks server reachability and displays status badges indicating active health or connection errors.
• Toggle state: You can temporarily disable an MCP server using the switch toggle without deleting its configuration or credentials.
• Delete a server: Click the trash icon next to any server to remove it. Orbit will prompt for confirmation. Once removed, tools from that server will no longer be available during subsequent agent runs.

​

Write-time SSRF guards and common rejections

• 422 INVALID_MCP_SERVER_URL: The server URL failed the security guard (e.g., non-HTTPS protocol, private IP address, or internal DNS resolution).
• 422 INVALID_MCP_OAUTH_TOKEN_URL: The OAuth2 token exchange URL failed the SSRF guard.
• 409 MCP_SERVER_NAME_CONFLICT: An MCP server with the same name already exists on this agent.

​

Register via the REST API

​

Add an MCP server with a Bearer token

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/agt_7e3b9c1f/mcp-servers" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "crm-tools",
    "server_url": "https://mcp.example.com/sse",
    "server_type": "http_sse",
    "auth_credentials": "sec_bearer_token_xyz"
  }'

​

Add an MCP server with OAuth2 Client Credentials

curl -X POST "https://api.orbit.devotel.io/api/v1/agents/agt_7e3b9c1f/mcp-servers" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "billing-tools",
    "server_url": "https://billing-mcp.example.com/sse",
    "server_type": "http_sse",
    "oauth2": {
      "grant_type": "client_credentials",
      "token_url": "https://auth.example.com/oauth/token",
      "client_id": "client_abc123",
      "client_secret": "secret_xyz789",
      "scope": "tools:read tools:execute"
    }
  }'

​

Response example

{
  "data": {
    "id": "mcpsrv_9f8e7d6c",
    "name": "crm-tools",
    "server_url": "https://mcp.example.com/sse",
    "server_type": "http_sse",
    "auth_kind": "bearer",
    "enabled": true,
    "created_at": "2026-10-07T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_mcpsrv_create",
    "timestamp": "2026-10-07T12:00:00.000Z"
  }
}

​

See also

• BYO MCP servers for AI agents — architecture, runtime discovery, and scope models.
• Hosted MCP server — exposing Orbit capabilities to external MCP clients.
• Orbit-as-MCP hosted server handshake — protocol details for inbound MCP.
• Troubleshooting: MCP server registration rejected — resolving SSRF guard rejections and naming conflicts.
• Build tenant custom tools for AI agents — single-endpoint HTTPS webhook tools.