> ## Documentation Index
> Fetch the complete documentation index at: https://help.craftcx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CraftCX MCP server

> Connect Cursor, Claude, Codex, and other MCP clients to CraftCX support intelligence and QA data

The CraftCX MCP server lets compatible AI assistants and coding agents read your CraftCX data through the [Model Context Protocol](https://modelcontextprotocol.io/). Once connected, an agent can search conversations, findings, customer signals, and support performance for your organization.

Access is authenticated with OAuth, scoped to one organization, and read-only.

## Quickstart

1. Add our remote MCP server to your agent of choice using the URL:

```bash theme={null}
https://mcp.craftcx.com/mcp
```

2. Authenticate with CraftCX via OAuth (run your agent mcp auth command)
3. Setup is complete

## Endpoint

| Transport       | URL                           |
| --------------- | ----------------------------- |
| Streamable HTTP | `https://mcp.craftcx.com/mcp` |

Protected resource metadata is available at:

```
https://mcp.craftcx.com/.well-known/oauth-protected-resource/mcp
```

## Authentication

CraftCX MCP uses OAuth. When you connect a client, it opens a browser flow so you can sign in to CraftCX and approve access for an organization.

You do not create an API token for MCP. Authorization uses your CraftCX account and the scopes you approve during consent.

## Permissions

Access will be granted using the following scopes;

| Scope                     | What it unlocks                                        |
| ------------------------- | ------------------------------------------------------ |
| `conversations:read`      | Support conversations, messages, scores, and topics    |
| `findings:read`           | QA findings and operational incidents                  |
| `signals:read`            | Customer signals and signal groups                     |
| `supportPerformance:read` | Aggregate AXIS scores, resolution outcomes, and trends |

Tools only appear when the session includes the matching scope. The MCP server is currently read-only.

## Available tools

| Tool                          | Description                                                                                    | Example use                                      |
| ----------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `whoami`                      | Return the authenticated user, organization, and approved scopes                               | Confirm which org and scopes the session can use |
| `list-signals`                | List recent customer signals                                                                   | See what surfaced most recently                  |
| `search-signals`              | Search persistent customer signals by text, type, and date                                     | Find refund or shipping signals in a date range  |
| `get-signal-group`            | Retrieve a signal group with trends and representative evidence                                | Inspect a recurring customer issue               |
| `search-signal-groups`        | Search signal groups by text and type, or list recent groups                                   | Find groups related to a product area            |
| `search-conversations`        | Search conversations by text, date, AXIS score, topic, and resolution status                   | Find low-scoring refund conversations            |
| `get-conversation`            | Retrieve a full conversation with messages, evaluations, scores, topics, findings, and signals | Dig into one conversation with evidence          |
| `analyze-support-performance` | Analyze aggregate AXIS scores, resolution outcomes, and trends                                 | Summarize quality over the last 30 days          |
| `search-findings`             | Search QA findings and incidents by text, priority, source, or status                          | List open high-priority findings                 |
| `get-finding`                 | Retrieve a finding or incident with evidence and related conversations                         | Review one finding end to end                    |
| `analyze-findings`            | Summarize emerging and unresolved findings and incidents                                       | Ask what needs attention this week               |

Learn more about the product concepts these tools return:

* [AXIS scoring](/features/axis-score)
* [Audit](/features/audit)
* [Support Observability](/support-observability/overview)
* [Policy monitoring](/support-observability/policy-monitoring)
* [Incidents](/support-observability/incidents)

## Setup

Most agents are smart enough for you to simply ask them;

> *Add the CraftCX MCP server - the remote URL is `https://mcp.craftcx.com/mcp`*

### Cursor

1. Open **Cursor Settings** → **MCP** → **Add new global MCP server**
2. Paste:

```json theme={null}
{
  "mcpServers": {
    "craftcx": {
      "url": "https://mcp.craftcx.com/mcp"
    }
  }
}
```

3. Save and restart Cursor if needed. Complete the OAuth flow the first time you use a CraftCX tool.

To share the config with your team, add the same block to `.cursor/mcp.json` in the project root.

### Claude Code

```bash theme={null}
claude mcp add --transport http craftcx https://mcp.craftcx.com/mcp
```

Then run `/mcp` in Claude Code and complete the OAuth flow.

### Codex

Add via the CLI using

```bash theme={null}
codex mcp add craftcx --url=https://mcp.craftcx.com/mcp
```

Or add the server to your `~/.codex/config.toml` file:

```toml theme={null}
[mcp_servers.craftcx]
url = "https://mcp.craftcx.com/mcp"
```

Then authenticate:

```bash theme={null}
codex mcp login craftcx
```

Complete the OAuth flow when prompted.

### OpenCode

CraftCX publishes an OpenCode remote config at:

```
https://craftcx.com/.well-known/opencode
```

That endpoint advertises the CraftCX MCP server. OpenCode loads it when you authenticate against a provider that supports [well-known remote config](https://opencode.ai/docs/config/).

You can also add the server by hand in `opencode.json` or `opencode.jsonc`:

```json theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "craftcx": {
      "type": "remote",
      "url": "https://mcp.craftcx.com/mcp",
      "oauth": {}
    }
  }
}
```

Then authenticate:

```bash theme={null}
opencode mcp auth craftcx
```

Complete the OAuth flow when prompted. See the [OpenCode MCP docs](https://opencode.ai/docs/mcp-servers/) for more options.

### VS Code (GitHub Copilot)

Create `.vscode/mcp.json` in your workspace:

```json theme={null}
{
  "servers": {
    "craftcx": {
      "type": "http",
      "url": "https://mcp.craftcx.com/mcp"
    }
  }
}
```

Open the Command Palette, run **MCP: List Servers**, start the CraftCX server, and complete OAuth when prompted.

### Claude Desktop

1. Open **Settings** → **Connectors**
2. Add a connector with URL `https://mcp.craftcx.com/mcp`
3. Complete the OAuth flow

### Other clients

If your tool supports remote MCP over Streamable HTTP, use:

```
https://mcp.craftcx.com/mcp
```

If the client only supports local stdio servers, bridge with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```json theme={null}
{
  "mcpServers": {
    "craftcx": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.craftcx.com/mcp"]
    }
  }
}
```

## Example prompts

Once connected, try questions like:

* "What are the open high-priority findings in CraftCX?"
* "Search CraftCX for conversations about refunds with low AXIS scores this month."
* "Summarize support performance for the last 30 days."
* "Show recent customer signal groups related to shipping delays."
* "Open conversation `<id>` and explain the findings and signals attached to it."

## Troubleshooting

* Complete the OAuth consent flow and select the correct organization.
* If tools are missing, confirm the session approved the matching `*:read` scopes.
* Disconnect and reconnect from your client's MCP settings if auth state looks stale.
* Confirm you can sign in to [app.craftcx.com](https://app.craftcx.com) with access to that organization.