Cliqtel AI Access (MCP)

Overview

MCP is an open standard for connecting AI applications to external systems through a uniform interface for tools, resources, and prompts. Cliqtel AI Access exposes the Cliqtel platform — numbers, SIP trunks, call flows, messaging, regulatory, and docs — as a set of MCP tools any compatible AI host can attach to.

The server is designed read-first and approval-gated: destructive or billable actions never execute without explicit authorization, and every tool call is audit-logged.

Endpoint & transport

The production MCP endpoint is:

https://mcp.cliqtel.com/mcp

Transport is Streamable HTTP (the modern MCP transport, supported by the OpenAI Responses API, Claude Desktop, Microsoft Copilot Studio, and the official SDKs). Sessions are stateless between HTTP requests; the server tracks context per bearer token.

Authentication

AI hosts authenticate with a Cliqtel-issued access token passed as a standard Bearer header:

Authorization: Bearer ct_mcp_...

Two flows are supported — pick the one that matches your host:

Option A — OAuth 2.1 with Dynamic Client Registration

The recommended path for hosts like Claude Desktop, Claude Code, and ChatGPT connectors. The host discovers the Authorization Server, registers itself, and walks the user through login + consent. No static token to copy.

1. Host connects to https://mcp.cliqtel.com/mcp and receives 401 Unauthorized with a WWW-Authenticate: Bearer resource_metadata=... header.
2. Host fetches https://mcp.cliqtel.com/.well-known/oauth-protected-resource (RFC 9728) to learn the Authorization Server (https://cliqtel.com).
3. Host fetches https://cliqtel.com/.well-known/oauth-authorization-server (RFC 8414) for endpoint URLs.
4. Host POSTs to /oauth/register (RFC 7591) with its redirect URIs and client name, and receives a client_id.
5. Host opens the user's browser to /oauth/authorize?response_type=code&client_id=...&redirect_uri=...&scope=mcp.inventory.read+mcp.docs.read&code_challenge=...&code_challenge_method=S256&state=....
6. User logs into their Cliqtel portal and sees a consent screen listing the requested scopes.
7. On Allow, Cliqtel redirects back with an authorization_code.
8. Host exchanges the code at /oauth/token with its code_verifier, and receives an access_token (1 h TTL) and a rotating refresh_token (30 d TTL).

PKCE with S256 is required — plaintext challenges are rejected. Refresh tokens are rotated on every use; reusing an old refresh token revokes all active sessions for that client as a replay defense.

Option B — Static MCP tokens

For headless hosts, custom integrations, or Copilot Studio you can issue a long-lived Cliqtel token directly from the customer portal under My Numbers → AI Access. Choose the scopes, name it, copy the plaintext once, and paste it into the host's bearer config.

Scope enforcement is identical across both flows. A token with mcp.inventory.read cannot place an order; a token with mcp.orders.draft cannot publish a route change.

Scopes

Every token is issued with a specific scope set. Scopes are additive and follow a mcp.<domain>.<action> namespace:

Scope	Grants	Tier
mcp.inventory.read	Read account inventory, numbers, trunks, DID assignments.	Discover
mcp.pricing.read	Read pricing, country coverage, product catalog.	Discover
mcp.docs.read	Search and fetch docs, setup guides, requirements.	Discover
mcp.callflows.read	Read call flow graphs and routing state.	Discover
mcp.callflows.draft	Create proposed call flow diffs (pending approval).	Automate
mcp.orders.draft	Draft number orders and reservations.	Automate
mcp.numbers.purchase	Execute approved number purchases.	Automate
mcp.routing.write	Commit approved routing changes.	Automate
mcp.messaging.send	Send SMS / WhatsApp (approval-gated over per-scope limit).	Automate

Tool catalog

Phase 1 ships eight read-only tools. Phase 2 adds draft-write tools behind approvals. Phase 3 adds privileged tools.

Read (Phase 1, live)

Tool	Purpose	Scope
search_numbers	Search available DIDs by country, type, capabilities.	inventory.read
list_inventory	List tenant's active numbers, trunks, DID assignments.	inventory.read
get_pricing	Pricing snapshot for a country and number type.	pricing.read
get_number_requirements	Regulatory & provisioning requirements.	docs.read
search_docs	Search setup guides and help articles.	docs.read
get_call_flow	Load a full call flow graph (nodes + edges).	callflows.read
list_call_flows	All DIDs with flow status (active / draft / none).	callflows.read
get_sip_config	Trunk registrar, username, status (no credentials).	inventory.read

Draft (Phase 2, coming)

• draft_order_number — create a draft order (pending user approval).
• reserve_number — short-lived number reservation.
• draft_call_flow_change — emit a proposed graph diff.
• generate_pbx_setup — produce 3CX / Asterisk / Teams config for a trunk.

Privileged (Phase 3, coming)

• purchase_number, assign_number, update_route, send_message, release_number — each gated by scope, approval policy, and rate limit.

Client setup

Claude Desktop

Open Settings → Connectors → Add Connector and paste:

https://mcp.cliqtel.com/mcp

Claude Desktop will automatically walk through OAuth 2.1 discovery, register itself via DCR, and open a browser tab for you to sign in to Cliqtel and approve the scopes. No token copy-paste needed.

OpenAI Responses API (ChatGPT)

{
  "model": "gpt-4.1",
  "tools": [{
    "type": "mcp",
    "server_label": "cliqtel",
    "server_url": "https://mcp.cliqtel.com/mcp",
    "headers": { "Authorization": "Bearer ct_mcp_..." }
  }],
  "input": "Find me a Dutch mobile number that supports SMS."
}

Microsoft Copilot Studio

In Copilot Studio, choose Add connector → MCP, paste the endpoint, and supply the bearer token. Scope selection happens at connector creation time.

Custom clients

Any client built on the official MCP SDKs (TypeScript, Python) can attach. We publish sample clients in the developer portal.

Approval workflow

Phase 2 tools create pending artifacts rather than executing immediately. Drafted orders, route changes, and bulk messaging send-outs appear in the customer portal with a Review & approve action.

Approvals can also be handled inline: when a draft is created, the chat widget pushes a prompt to the signed-in user via Reverb. One click approves or rejects. Until approved, the MCP tool response returns a pending_approval status with a link to the approval screen.

Audit & observability

Every MCP tool call is written to the mcp_tool_calls audit table with:

• Call UUID, timestamp, duration.
• User ID, token ID, MCP client identifier.
• Tool name, scope required, arguments.
• Status (ok / error / running) and safe result metadata.

Administrators can export this log from the admin audit view. Anomalous patterns (scope misuse, error spikes) trigger Slack alerts.

Rate limits

Tier	Tool calls / month	Burst / min	Connections
Discover	10,000	60	1
Automate	100,000	300	5
Embed / OEM	Unlimited	Custom	Unlimited

Overages on Automate are billed at €0.0005 per call. Underlying telecom actions (numbers, messages, voice minutes) are billed at standard Cliqtel rates regardless of tier.

Roadmap

• Phase 1 (live) — eight read-only tools, bearer-token auth, audit log.
• Phase 2 (live) — draft-write tools, portal approval UI, chat-widget approval prompts.
• Phase 3 (live) — OAuth 2.1 + PKCE + dynamic client registration, per-token rate limits, Slack alerting on error spikes, production endpoint at mcp.cliqtel.com.
• Phase 4 — privileged write tools (purchase_number, update_route, send_message), white-label MCP endpoints per partner, prompt primitives (Teams Direct Routing, 3CX setup, office rollout).