Skip to main content

Connecting an AI client

Beta

MCP is in preview, and you must turn it on for your account before any connection works.

There are two ways to connect, by who is behind the client:

  • A person's assistant (Claude, ChatGPT, an IDE) → OAuth 2.1. The person signs in on Telebroad's screen and the client gets a token scoped to what that user can already see.
  • A machine or back-end → an API key.

The endpoint is the same for both:

https://api.account.telebroad.com/mcp

It speaks Streamable HTTP: a single POST carries every JSON-RPC message, and each gets one JSON response. (A GET returns 405 — there is no server-push stream.) Use the URL exactly as shown: /mcp sits at the domain root, not under /api/... like the rest of the API. Your access token is tied to this exact URL, so a different path won't be accepted.

Connect over OAuth​

Most MCP clients do this for you. You paste the URL in, and the client:

  1. hits /mcp with no token, gets a 401 with a WWW-Authenticate header pointing at Telebroad's discovery document,
  2. discovers the OAuth endpoints and registers itself automatically (no setup on your side — there is no client secret),
  3. opens your browser to Telebroad's sign-in and approval screen,
  4. stores the returned token and starts making calls.

So in practice: add the server URL, click Approve, done.

Doing it by hand​

If you are building your own client, the flow is the standard Telebroad OAuth 2.1 flow — authorization code + PKCE, dynamic client registration, no client secret. It is documented step by step in OAuth 2.1; everything there applies. The MCP-specific details:

DetailWhat to know
Discovery (what to read first)GET /.well-known/oauth-protected-resource — names the MCP resource and its authorization server. Then /.well-known/oauth-authorization-server for the endpoints.
ScopeRequest reports:read. It is the only scope the MCP endpoint enforces, and the default if you request none.
AudienceTokens are bound to the MCP resource URL. A token minted for another resource is rejected here.
Client idRegistration returns a public tbmcp_… client id. No secret is issued — PKCE (S256) is required and takes its place.
Token lifeAccess token ~1 hour; refresh token rotates on every use (save the newest).

A request with a missing or bad token returns 401 with:

WWW-Authenticate: Bearer resource_metadata="https://api.account.telebroad.com/.well-known/oauth-protected-resource"

— which is exactly the hint that lets a compliant client discover and run the flow on its own.

Read endpoints from discovery

As with the rest of OAuth, read the authorization, token and registration URLs from the discovery document at runtime rather than hard-coding them. See OAuth → Discover.

Connect with an API key​

For a back-end or script with no human to sign in, use an API key instead. The key must carry the reports:read scope, and its source IP must be allow-listed like any API-key request.

Send it as a bearer token (or X-API-Key):

curl -X POST 'https://api.account.telebroad.com/mcp' \
  -H "Authorization: Bearer $TB_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

One difference from OAuth worth knowing: an API-key connection is gated only by the account-level MCP switch, not by a per-user permission (there is no user behind a key). So on an enabled account, any key with reports:read reaches MCP — narrow or revoke the key itself to control that. See Enabling MCP.

Next​

Once connected, see what the assistant can actually do in Tools & resources.