MCP endpoint discovery — worked sample - Devotel Orbit Documentation

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.devotel/orbit-cpaas",
  "description": "Orbit's hosted remote MCP server: drive a caller's own Orbit CPaaS tenant (SMS, WhatsApp, voice, contacts, campaigns, analytics) over Streamable-HTTP JSON-RPC — no local process.",
  "version": "1.0.0",
  "protocolVersion": "2025-06-18",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://api.orbit.devotel.io/mcp"
    }
  ],
  "documentation": "https://docs.orbit.devotel.io/guides/mcp-claude-cursor",
  "auth": {
    "type": "api-key",
    "headers": ["Authorization: Bearer <key>", "X-API-Key: <key>"],
    "docs": "https://docs.orbit.devotel.io/authentication",
    "note": "Bring your own Orbit API key (dv_live_sk_* / dv_test_sk_* for a zero-charge sandbox trial). Every tool call runs with that key's own scopes and tenant — there is no separate MCP-specific credential."
  }
}

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.devotel/orbit-cpaas",
  "description": "Orbit's hosted remote MCP server: drive a caller's own Orbit CPaaS tenant (SMS, WhatsApp, voice, contacts, campaigns, analytics) over Streamable-HTTP JSON-RPC — no local process.",
  "version": "1.0.0",
  "protocolVersion": "2025-06-18",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://api.orbit.devotel.io/mcp"
    }
  ],
  "documentation": "https://docs.orbit.devotel.io/guides/mcp-claude-cursor",
  "auth": {
    "type": "api-key",
    "headers": ["Authorization: Bearer <key>", "X-API-Key: <key>"],
    "docs": "https://docs.orbit.devotel.io/authentication",
    "note": "Bring your own Orbit API key (dv_live_sk_* / dv_test_sk_* for a zero-charge sandbox trial). Every tool call runs with that key's own scopes and tenant — there is no separate MCP-specific credential."
  }
}

Worked MCP discovery sample

An MCP client (Claude, Cursor, a registry crawler) reads this manifest before it ever connects: it learns the hosted server’s transport URL, the MCP protocol revision it speaks, and exactly how to authenticate — then hands the user a one-click “add server” instead of asking for a URL.

GET /api/v1/public/mcp/.well-known/mcp.json — public, no API key required.

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.devotel/orbit-cpaas",
  "description": "Orbit's hosted remote MCP server: drive a caller's own Orbit CPaaS tenant (SMS, WhatsApp, voice, contacts, campaigns, analytics) over Streamable-HTTP JSON-RPC — no local process.",
  "version": "1.0.0",
  "protocolVersion": "2025-06-18",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://api.orbit.devotel.io/mcp"
    }
  ],
  "documentation": "https://docs.orbit.devotel.io/guides/mcp-claude-cursor",
  "auth": {
    "type": "api-key",
    "headers": ["Authorization: Bearer <key>", "X-API-Key: <key>"],
    "docs": "https://docs.orbit.devotel.io/authentication",
    "note": "Bring your own Orbit API key (dv_live_sk_* / dv_test_sk_* for a zero-charge sandbox trial). Every tool call runs with that key's own scopes and tenant — there is no separate MCP-specific credential."
  }
}

The body follows the official MCP Registry server.json shape, so aggregators can ingest it without a bespoke parser. Each field tells the client something actionable:

$schema / name / version — the registry identity of this server. name is the io.devotel/orbit-cpaas namespace the entry is published under; version tracks the hosted tool catalog and bumps when the catalog changes shape.
protocolVersion — the MCP protocol revision the server speaks (2025-06-18). A client checks this before negotiating a session, so an outdated client warns instead of failing mid-handshake.
remotes — the transport the client connects to. Single entry today: streamable-http at POST /api/v1/mcp — no stdio subprocess, no SSE fallback to configure.
documentation — the setup walkthrough (Claude and Cursor config blocks) at Connect Claude or Cursor.
auth — driven off your ordinary Orbit API key, passed as either Authorization: Bearer <key> or X-API-Key: <key>. Tool calls inherit the key’s scopes and tenant, so a read-scoped key gets read-scoped tools and nothing else.

The response sends Cache-Control: public, max-age=300, stale-while-revalidate=600, so aggregators can cache it at the edge and re-fetch at most every five minutes. Content is identical for every caller — the manifest describes the server, never your tenant; no tenant-specific data is exposed on this unsigned path.

Deciding errors

Unauthenticated discovery failures are rare. When a request does fail, the branch is one of these:

Class	Meaning	Branch response
429 `RATE_LIMITED`	The public-read ceiling for unsigned callers tripped.	Retry after `error.details.retry_after`. Identical for every caller, so cached copies are usually fresher than the retry window anyway.
401/403 once connected	Not from this endpoint — from `POST /api/v1/mcp` when the key you configured is missing or read-scoped.	Fix the key, not the manifest. The manifest stays valid; the session handshake is what rejected it.

The retry-vs-terminal decision table lives in the error-handling guide.

API Reference

All Endpoints

MCP endpoint discovery — worked sample

Worked MCP discovery sample

Deciding errors

​Worked MCP discovery sample

​Deciding errors

Worked MCP discovery sample

Deciding errors