MCP session init / message dispatch

POST

/mcp

curl --request POST \
  --url https://mcp.infiniteaudience.ai/mcp \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": { "name": "my-client", "version": "1.0" } } }'

• MCP streaming server through the shared public HTTPS load balancer

Without mcp-session-id: initialises a new MCP session (body must be an Initialize request). With mcp-session-id: dispatches a message to the existing session.

Authorizations

• bearerAuth

Parameters

Header Parameters

mcp-session-id

string

Session ID returned from the Initialize response. Omit on first call.

Request Body^required

Media typeapplication/json

JSON-RPC 2.0 request envelope. On first call (no mcp-session-id), method must be initialize. Subsequent calls dispatch to any available MCP tool (see the MCP — Available Tools section below).

object

jsonrpc

required

JSON-RPC version. Always "2.0".

string

Allowed values: 2.0

method

required

RPC method name. initialize on session creation; a tool name (e.g. tools/call) on subsequent dispatches.

string

id

One of:

string

string

integer

integer

null

null

params

Method-specific parameters. For initialize, pass protocol version and client capabilities. For tools/call, pass name (tool name) and arguments (tool input object).

object

key

additional properties

any

Examples

Session initialization

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0"
    }
  }
}

Invoke a tool

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_audiences",
    "arguments": {}
  }
}

Responses

200

MCP response — JSON-RPC 2.0 envelope.

Media typeapplication/json

object

jsonrpc

required

string

Allowed values: 2.0

id

One of:

string

string

integer

integer

null

null

result

Present on success; shape depends on the MCP method called.

error

Present on failure.

object

code

required

integer

message

required

string

Example

{
  "jsonrpc": "2.0"
}

400

Invalid request — malformed body, missing required attribute, or failed validation. See error and message for details.

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

Examplevalidation_error

{
  "error": "Bad Request",
  "code": "MISSING_SEGMENTS",
  "message": "segment_ids is required for filter audiences."
}

401

Missing or invalid Bearer token. Obtain one via POST /v1/auth/token. When a token was supplied but rejected, code distinguishes TOKEN_EXPIRED (the token’s lifetime has passed — request a new one via POST /v1/auth/token and retry) from TOKEN_INVALID (malformed or revoked — re-authenticate).

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

{
  "error": "Unauthorized: Missing or invalid Authorization header"
}

{
  "error": "Unauthorized",
  "code": "TOKEN_EXPIRED",
  "message": "Your session has expired. Please sign in again."
}

403

Token is valid but lacks the required scope for this endpoint. Check the endpoint description for the required scope (discovery, purchase, or account).

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

Examplemissing_scope

{
  "error": "SCOPE_REQUIRED",
  "message": "This endpoint requires the purchase scope."
}

404

Resource not found or not accessible to the calling org.

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

Examplenot_found

{
  "error": "Audience not found"
}