Article

MCP & OpenAPI Integration

The MX8 Labs platform exposes both a standard OpenAPI REST API and a Model Context Protocol (MCP) server. The REST API lets you build traditional integrations (scripts, dashboards, internal tools), while the MCP server lets AI assistants like Claude, ChatGPT, and Cursor interact with your surveys and reports conversationally.

Both interfaces share the same underlying platform and are secured with OAuth 2.0 or API key authentication.

Quick Reference

Resource	URL
OpenAPI spec	`https://api.app.mx8.io/openapi.json`
API base URL	`https://api.app.mx8.io`
MCP server	`https://mcp.dev.mx8.io/`
OAuth discovery	`https://mcp.dev.mx8.io/.well-known/oauth-authorization-server`

Authentication

The API and MCP server support two authentication methods.

OAuth 2.0 Bearer Token. Use the authorization code flow for interactive applications and MCP clients. Before you can authenticate, contact your MX8 Labs representative to register your callback URL. Without this step, the OAuth handshake will fail. The authorization server metadata is published at https://mcp.dev.mx8.io/.well-known/oauth-authorization-server. Point your OAuth client at that URL to auto-discover the authorization and token endpoints, supported scopes, and grant types.

A typical OAuth flow looks like this:

Your application redirects the user to the MX8 Labs authorization endpoint with your registered callback URL.
The user authenticates and grants access.
MX8 Labs redirects back to your callback URL with an authorization code.
Your application exchanges the code for an access token at the token endpoint.
Include the token as a Bearer token in the Authorization header on subsequent requests.

API Key. For server-to-server integrations, you can authenticate by passing your API key in the access_token header. Contact your MX8 Labs representative to obtain an API key.

OpenAPI (REST)

The full OpenAPI 3.1 specification is available at https://api.app.mx8.io/openapi.json. You can import it into tools like Postman, Swagger UI, or any OpenAPI-compatible client to explore available endpoints, request schemas, and response formats.

The API currently exposes four endpoints under the v2 API namespace at https://api.app.mx8.io.

GET /v2/surveys. Lists all surveys the authenticated user can access. Returns an array of survey summaries including each survey's ID, name, project, response counts, and the timestamp of the last response.

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     https://api.app.mx8.io/v2/surveys

Example response:

[
  {
    "id": 42,
    "name": "Brand Awareness Q1 2026",
    "project": "Brand Health",
    "current_responses": 312,
    "target_responses": 500,
    "expected_responses": 500,
    "last_response": "2026-04-10T14:23:00Z"
  }
]

GET /v2/surveys/{survey_id}. Fetches a single survey by its integer ID. Returns the full survey detail including the survey code and question definitions (each with an id, question_text, and reporting_label).

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     https://api.app.mx8.io/v2/surveys/42

POST /v2/surveys/{survey_id}/report. Runs a cross-tab report for a survey. The request body specifies which question IDs to use as row and column variables.

curl -X POST \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"row_ids": [5], "column_ids": [12]}' \
     https://api.app.mx8.io/v2/surveys/42/report

Parameter	Type	Required	Description
`survey_id`	`integer`	yes	Path parameter. The ID of the survey to report on.
`row_ids`	`array[integer]`	yes	1–2 question IDs to use as row variables.
`column_ids`	`array[integer]`	yes	0–2 question IDs for column variables. Pass an empty array `[]` for a frequency-only report.

The response is a CrossTab object containing headerColumns, valueColumns, and rows. Each row includes header values and column values with counts (n), percentages (val), error margins (err), and optional statistical test results (stat_test).

POST /v2/feasibility. Runs audience feasibility and cost estimation for a text-based audience definition. This endpoint accepts a natural-language audience description along with planning inputs and returns provider-level feasibility results.

curl -X POST \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "audience_definition_text": "US adults 25-54, household income $75k+",
       "market": "US",
       "language": "en",
       "target_responses": 500,
       "estimated_ir": 0.35,
       "estimated_duration": 10,
       "days_in_field": 7
     }' \
     https://api.app.mx8.io/v2/feasibility

Parameter	Type	Required	Description
`audience_definition_text`	`string`	yes	Natural-language description of the target audience.
`market`	`string`	yes	Market code (e.g., `"US"`, `"GB"`).
`language`	`string`	yes	Language code (e.g., `"en"`).
`target_responses`	`integer`	yes	Number of completed responses you need.
`estimated_ir`	`number`	yes	Estimated incidence rate, between 0 and 1.
`estimated_duration`	`integer`	yes	Estimated survey length in minutes.
`days_in_field`	`integer`	yes	Number of days the survey will be in field.

The response includes the overall feasibility status, the best provider, estimated cost per interview, and per-provider breakdowns.

MCP Server

The MCP server at https://mcp.dev.mx8.io/ implements the Model Context Protocol and allows AI-powered tools to interact with your MX8 Labs account. Any MCP-compatible client (Claude Desktop, Claude Code, Cursor, and others) can connect to it.

To connect, add the MX8 Labs MCP server in your client's configuration. For example, in Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "mx8-labs": {
      "url": "https://mcp.dev.mx8.io/"
    }
  }
}

On first use, your client will walk you through the OAuth flow described above.

Available MCP Tools

The MCP server currently exposes three tools. Each requires a valid authenticated session.

list_surveys. Returns the surveys the authenticated user is allowed to access. Use it as the entry point to discover valid survey IDs before calling other tools. Takes no parameters.

get_survey. Fetches a single survey by its ID, including the survey code and question definitions. Use it when you need the full survey structure or specific question IDs for reporting.

Parameter	Type	Required	Description
`survey_id`	`integer`	yes	The ID of the survey to retrieve.

run_report. Runs an external cross-tab report for a survey. You specify which questions to place on rows and columns, and the tool returns the tabulated output.

Parameter	Type	Required	Description
`survey_id`	`integer`	yes	The ID of the survey to report on.
`row_ids`	`array[integer]`	yes	1–2 question IDs to use as row variables.
`column_ids`	`array[integer]`	yes	0–2 question IDs for column variables. Pass an empty array for a frequency-only report.

Example prompt to an MCP-connected assistant: "Show me the cross-tab of Q3 by Q7 for survey 42."

Getting Started

Register your callback URL. Contact your MX8 Labs representative and provide the OAuth redirect URI for your application or MCP client. If you prefer API key auth for server-to-server use, request an API key instead.
Choose your integration path. Use the REST API for programmatic access, the MCP server for AI-assisted workflows, or both.
Authenticate. Point your client at the OAuth discovery URL and complete the authorization flow, or pass your API key in the access_token header.
Start with list surveys. Whether you are making REST calls or using the MCP tools, calling GET /v2/surveys (or the list_surveys MCP tool) is the natural first step.

Additional Methods

The current API covers survey discovery, survey details, cross-tab reporting, and audience feasibility estimation. If you have use cases that require additional methods (data exports, respondent management, survey creation), reach out to your MX8 Labs representative. The API is under active development and new capabilities are added based on client needs.