MCP discovery manifest — worked sample - Devotel Orbit Documentation

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "send_sms",
        "description": "Send an SMS message from a number on the caller's Orbit account to an E.164 phone number.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "to": { "type": "string", "description": "Recipient phone number, E.164 preferred (e.g. +14155551234)." },
            "from": { "type": "string", "description": "Sending number owned by this tenant, E.164 (e.g. +14155559876)." },
            "body": { "type": "string", "description": "SMS message text (max 1600 chars)." }
          },
          "required": ["to", "from", "body"],
          "additionalProperties": false
        }
      },
      {
        "name": "list_campaigns",
        "description": "List messaging/voice campaigns on this tenant, newest first.",
        "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false }
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "send_sms",
        "description": "Send an SMS message from a number on the caller's Orbit account to an E.164 phone number.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "to": { "type": "string", "description": "Recipient phone number, E.164 preferred (e.g. +14155551234)." },
            "from": { "type": "string", "description": "Sending number owned by this tenant, E.164 (e.g. +14155559876)." },
            "body": { "type": "string", "description": "SMS message text (max 1600 chars)." }
          },
          "required": ["to", "from", "body"],
          "additionalProperties": false
        }
      },
      {
        "name": "list_campaigns",
        "description": "List messaging/voice campaigns on this tenant, newest first.",
        "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false }
      }
    ]
  }
}

Hosted MCP server discovery manifest (public)

Orbit runs a hosted remote MCP server at POST /api/v1/mcp (Streamable-HTTP JSON-RPC) that lets an MCP-aware agent host or aggregator drive Orbit’s CPaaS capabilities — messaging, voice, contacts, campaigns, analytics — without running a local process. But callers need to know the server exists before they hold an Orbit API key. This public, unauthenticated endpoint fills that gap: it returns a standard MCP Registry server.json-shaped manifest that aggregators, crawlers, and MCP clients can read to auto-discover and auto-configure the server. The same manifest is also served from two self-serve copies — https://orbit.devotel.io/.well-known/mcp.json for self-hosted discovery and apps/mcp-server/server.json in the repo — kept in lockstep so every discovery path sees the same payload.

Response example

200

{
  "$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/api/v1/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."
  }
}

Field	Description
`name`	The MCP Registry namespace for Orbit’s hosted server. Aggregators key on this to deduplicate listings.
`version`	The hosted server version. Tracks the tool catalog; bumping it signals that the available tool set changed.
`protocolVersion`	The MCP protocol revision the server speaks. Callers should negotiate to the highest version they support up to this one.
`remotes[0].url`	The Streamable-HTTP endpoint for actual JSON-RPC calls (`POST /api/v1/mcp`). This is the URL an aggregator passes to its MCP client transport.
`auth`	Hints for clients that need to configure authentication. Orbit tool calls use the same Orbit API keys as every other REST route — no separate MCP credential.
`documentation`	Link to the MCP setup guide on the Orbit docs site.

Verify the manifest caches correctly

The response carries a Cache-Control: public, max-age=300, s-maxage=300, stale-while-revalidate=600 header. Manifest contents change rarely (only when the hosted server version is bumped), so aggregators can cache the response for up to five minutes and serve stale content for ten minutes while revalidating in the background. Treat the version field as eventually consistent — a newly deployed tool catalog may take up to the cache window to surface. Before your aggregator hard-codes the manifest, fetch it once and assert the cache headers are as above and the remotes[0].url matches the endpoint you will POST to. That way a version bump or a URL change surfaces at setup time, not after your client has cached a stale copy.

Calling the server: POST /api/v1/mcp

Unlike the discovery manifest above, the JSON-RPC endpoint is authenticated — pass your Orbit API key as X-API-Key: <key> or Authorization: Bearer <key>, the same way every other REST route authenticates. The route accepts a single JSON-RPC 2.0 envelope per request: {"jsonrpc":"2.0","id":<number or string>,"method":"<name>","params":{...}}. Four methods are wired: initialize, tools/list, tools/call, and notifications/initialized. A request with no id (or id: null) is a JSON-RPC notification and returns 202 with no body.

tools/list — enumerate what your key can call

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/mcp" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/mcp', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }),
})
console.log(await res.json())

Python

import os, requests

r = requests.post(
    "https://api.orbit.devotel.io/api/v1/mcp",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"},
    json={"jsonrpc": "2.0", "id": 1, "method": "tools/list"},
)
print(r.json())

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "send_sms",
        "description": "Send an SMS message from a number on the caller's Orbit account to an E.164 phone number.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "to": { "type": "string", "description": "Recipient phone number, E.164 preferred (e.g. +14155551234)." },
            "from": { "type": "string", "description": "Sending number owned by this tenant, E.164 (e.g. +14155559876)." },
            "body": { "type": "string", "description": "SMS message text (max 1600 chars)." }
          },
          "required": ["to", "from", "body"],
          "additionalProperties": false
        }
      },
      {
        "name": "list_campaigns",
        "description": "List messaging/voice campaigns on this tenant, newest first.",
        "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false }
      }
    ]
  }
}

Only tools your API key’s scopes unlock are listed — the catalog is default-deny, so an unscoped key sees an empty tools array.

tools/call — send_sms (messaging.send SMS)

The canonical write tool: send an SMS. The params.name is the exact tool name from tools/list; params.arguments is the validated input object.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/mcp" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"send_sms","arguments":{"to":"+14155551234","from":"+14155559876","body":"Your verification code is 884213"}}}'

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/mcp', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 2,
    method: 'tools/call',
    params: {
      name: 'send_sms',
      arguments: {
        to: '+14155551234',
        from: '+14155559876',
        body: 'Your verification code is 884213',
      },
    },
  }),
})
const envelope = await res.json()
console.log(JSON.parse(envelope.result.content[0].text))

Python

import json, os, requests

r = requests.post(
    "https://api.orbit.devotel.io/api/v1/mcp",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"},
    json={
        "jsonrpc": "2.0",
        "id": 2,
        "method": "tools/call",
        "params": {
            "name": "send_sms",
            "arguments": {
                "to": "+14155551234",
                "from": "+14155559876",
                "body": "Your verification code is 884213",
            },
        },
    },
)
envelope = r.json()
print(json.loads(envelope["result"]["content"][0]["text"]))

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\":\"msg_01H8ZjK3aBcD7fE9gHjKmNp\",\"to\":\"+14155551234\",\"from\":\"+14155559876\",\"status\":\"queued\"}"
      }
    ],
    "isError": false
  }
}

The tool result inverts the usual MCP shape so an LLM gets the payload as text: result.content[0].text holds the JSON-stringified body of the underlying Orbit REST response. When the underlying call returns a non-2xx, result.isError is true and the same envelope still comes back with HTTP 200. Always check isError before acting on the text payload.

Error envelopes

Failures come back as a JSON-RPC error object — {"jsonrpc":"2.0","id":<your id>,"error":{"code":<number>,"message":"<reason>"}}. HTTP status is still 200.

Situation	Code
Unknown method name	`-32601` Method not found
Malformed envelope (missing `method`, bad JSON)	`-32600` Invalid Request
`tools/call` with missing/typed-bad arguments	`-32602` Invalid params (with `data.missing_arguments`)
Tool doesn’t exist, or key lacks the scope for it	`-32001` Tool not found

The -32001 code is deliberately the same for “unknown tool” and “known but unscoped”: an unscoped caller cannot probe which tools exist. The example below uses a key without the messages:write scope.

curl -X POST "https://api.orbit.devotel.io/api/v1/mcp" \
  -H "X-API-Key: dv_live_sk_a_key_without_messages_scope" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"send_sms","arguments":{"to":"+14155551234","from":"+14155559876","body":"hi"}}}'

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32001,
    "message": "Tool not found"
  }
}

Grant the missing scope on the key in Settings → API keys, or request access from a workspace admin.

No authentication on the discovery manifest

The discovery route above is registered before API-key authentication in the app’s middleware chain (pre-auth, the same way the health probe and well-known agent-keys routes are) — genuinely unauthenticated by design, not just documented that way. Aggregators, registry crawlers, and MCP client transports call it without an API key. Only the actual JSON-RPC endpoint (POST /api/v1/mcp) requires the key.

Next steps

Full walkthrough: the MCP server guide covers the Claude/Cursor client setup and the full tool catalog.
Scopes: every tool name maps to a regular Orbit API-key scope — see authentication.
Self-hosted twin files: https://orbit.devotel.io/.well-known/mcp.json and the repo file apps/mcp-server/server.json carry the same manifest for local-process and self-hosted discovery paths.

API Reference

All Endpoints

MCP discovery manifest — worked sample

Hosted MCP server discovery manifest (public)

Response example

Verify the manifest caches correctly

Calling the server: POST /api/v1/mcp

tools/list — enumerate what your key can call

tools/call — send_sms (messaging.send SMS)

Error envelopes

No authentication on the discovery manifest

Next steps

​Hosted MCP server discovery manifest (public)

​Response example

​Verify the manifest caches correctly

​Calling the server: POST /api/v1/mcp

​tools/list — enumerate what your key can call

​tools/call — send_sms (messaging.send SMS)

​Error envelopes

​No authentication on the discovery manifest

​Next steps

Hosted MCP server discovery manifest (public)

Response example

Verify the manifest caches correctly

Calling the server: POST /api/v1/mcp

tools/list — enumerate what your key can call

tools/call — send_sms (messaging.send SMS)

Error envelopes

No authentication on the discovery manifest

Next steps