Aventora Engagement Hub — MCP Server

The Engagement Hub exposes a Model Context Protocol (MCP) server so Cursor, Claude Desktop, Claude Custom Connectors, and other MCP clients can start and inspect engagements with named tools. The tools wrap existing Hub REST APIs. They do not add new engagement behavior.

Related: Start API · CRM MCP · API Security Model

Endpoint

POST {HUB_BASE_URL}/mcp
Authorization: Bearer <HUB_API_KEY or MCP OAuth access token>
Content-Type: application/json

API-key clients use the same account-scoped Hub API key you use for POST /integration/start. Claude Custom Connectors use an MCP OAuth token (mcp:tools only). Never use platform admin or domain-chatbot internal keys.

Protocol: JSON-RPC 2.0 over Streamable HTTP. POST /mcp returns HTTP 200 and Content-Type: application/json (no charset). Notifications (notifications/*) return HTTP 202 with an empty body. The server echoes a supported protocol version (2024-11-05, 2025-03-26, or 2025-06-18).

Cursor config

{
  "mcpServers": {
    "aventora-hub": {
      "type": "streamable-http",
      "url": "https://phone.aventora.ai/mcp",
      "headers": {
        "Authorization": "Bearer [HUB_API_KEY]"
      }
    }
  }
}

Replace the URL with your Hub host. Store the API key only on the client that should act as that Hub account.

Claude Custom Connector (OAuth)

Claude Custom Connectors use OAuth 2.1 authorization-code + PKCE against Engagement Hub. They do not use a stored Hub API key.

Unauthenticated browsers hitting GET /oauth/authorize see a Hub sign-in page (Google or Microsoft). After calendar OAuth returns to /oauth/authorize, Hub shows consent. Allowing Claude issues an authorization code. Token exchange is PKCE S256 only (authorization_code and refresh_token). There is no client_credentials grant.

Claude may request api profile mcp:tools. Authorization-server metadata advertises those three scopes so Claude’s connector matches the CRM shape. Hub grants only mcp:tools. The access token is bound to {HUB origin}/mcp and does not work on POST /integration/start or other Hub REST routes. A request that omits mcp:tools is rejected.

The consenting Google/Microsoft user must already be linked to a Hub accounts row. Unlinked users are refused.

Operator: create the Claude OAuth client

Run once per Hub deployment (or --rotate to issue a new secret). The plaintext secret is printed once and stored only as a SHA-256 hash.

python scripts/register_claude_mcp_client.py

Docker:

docker compose exec aventora-assistant python scripts/register_claude_mcp_client.py

Optional: --client-id <id> (default claude-aventora-hub), --account-id <account-uuid> to bind the client to one tenant, --rotate.

Copy CLIENT_ID and CLIENT_SECRET from the command output. Do not commit the secret.

Registered redirect URIs (exact match):

https://claude.ai/api/mcp/auth_callback
https://claude.com/api/mcp/auth_callback

Values to enter in Claude

Field	Value
Connector name	Aventora Engagement Hub
MCP URL	`https://{hub-host}/mcp` (must match `GET /.well-known/oauth-protected-resource/mcp` → `resource`)
OAuth Client ID	`claude-aventora-hub` (or the `--client-id` you passed)
OAuth Client Secret	the generated secret from the command

Unauthenticated POST /mcp returns 401 with:

WWW-Authenticate: Bearer realm="mcp", resource_metadata="https://{hub-host}/.well-known/oauth-protected-resource/mcp"

Public origin for those URLs is HUB_SERVER_URL, then ENGAGEMENT_HUB_PUBLIC_URL, SERVER_URL, PUBLIC_URL. MCP access tokens are signed with CHAT_TOKEN_SECRET (fallback SECRET_KEY).

Manual certification

Rebuild the Hub image after this change (a container restart is not enough).
Add the connector in Claude with the values above.
Click Connect.
Sign in with a Google or Microsoft user that is linked to the Hub account.
Allow Claude on the consent page. Confirm the callback to Claude completes.
Confirm Claude discovers MCP tools.
Run tools/list.
Execute a read-only call such as hub_list_recent_calls or hub_get_availability.
Confirm Cursor / API-key POST /mcp still works independently.

Dynamic Client Registration is not enabled in this phase.

Methods

Method	Purpose
`initialize`	Handshake and server metadata
`ping`	Health check
`tools/list`	Named tools this API key is allowed to call
`tools/call`	Run a tool (`params.name` + `params.arguments`)
`prompts/list`	Empty (not used)
`resources/list`	Empty (not used)

Invalid or missing Bearer tokens return HTTP 401 with WWW-Authenticate protected-resource metadata. Tool execution failures return HTTP 200 with MCP result.isError: true and the error text. Protocol errors return HTTP 200 with a JSON-RPC error object.

Tools (v1)

tools/list only includes tools the key is permitted to use.

Tool	Wraps	Required permission
`hub_start_engagement`	`POST /integration/start`	`call_management`
`hub_get_engagement`	`GET /integration/engagement/{id}`	`call_management`
`hub_pause_engagement`	`POST /integration/pause`	`call_management`
`hub_cancel_engagement`	`POST /integration/cancel`	`call_management`
`hub_get_availability`	`GET /calendar/availability`	`calendar_read`
`hub_book_appointment`	`POST /calendar/book`	`calendar_write`
`hub_list_recent_calls`	`GET /call_logs` (limit capped at 50; no transcript)	`call_logs_read`
`hub_get_call_result`	`GET /result/{call_sid}` (`include_transcript` default false)	`call_logs_read`
`hub_crm_sync_report`	`GET /crm-sync/report` (read only)	`call_logs_read`
`hub_list_analysis_schema`	Allowlisted reporting sources, columns, and metrics	`call_logs_read`
`hub_query_call_logs`	Call logs query (`start_date`, `end_date`, `channels`; limit capped at 200)	`call_logs_read`
`hub_aggregate_engagement_facts`	Campaign intelligence aggregates (date range + channel)	`call_logs_read`
`hub_get_call_stats`	Account call totals for a date range and optional channels	`call_logs_read`
`hub_list_ask_ai_reports`	Catalog of 15 predefined Ask AI reports	`call_logs_read`
`hub_run_ask_ai_report`	Run a predefined Ask AI report by `report_id`	`call_logs_read`

hub_start_engagement still requires phone_number, domain_name, source_record_id, and source_org_id.

This server does not expose bulk blast, CRM resync, billing mutation, admin/cross-account queries, or recording URLs. Analysis tools are read-only and account-scoped. The in-product Ask AI agent is not behind /mcp — Cursor and Claude already act as the agent.

Example

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "hub_start_engagement",
    "arguments": {
      "phone_number": "+15555550100",
      "domain_name": "acme",
      "source_record_id": "person-123",
      "source_org_id": "workspace-456",
      "channel": "sms",
      "instruction": "Follow up on the quote"
    }
  }
}

Changelog

Date	Change
2026-08-19	Read-only analysis tools: `hub_list_analysis_schema`, `hub_query_call_logs` (cap 200), `hub_aggregate_engagement_facts`, `hub_get_call_stats`, `hub_list_ask_ai_reports`, `hub_run_ask_ai_report`. Each query tool accepts `start_date`, `end_date`, and `channels`.
2026-08-18	Claude Custom Connectors: OAuth 2.1 authorization-code + PKCE, discovery, and Hub sign-in/consent. Claude may request `api profile mcp:tools`; Hub grants only `mcp:tools`. MCP OAuth tokens do not work on Hub REST (`/integration/start`). API keys still work on `POST /mcp`. Operator script: `scripts/register_claude_mcp_client.py`. Rebuild the Hub image after this change.
2026-08-18	Initial Engagement Hub MCP (`POST /mcp`) with named engagement, calendar, and read-only call tools.

Endpoint​

Cursor config​

Claude Custom Connector (OAuth)​

Operator: create the Claude OAuth client​

Values to enter in Claude​

Manual certification​

Methods​

Tools (v1)​

Example​

Changelog​