> For the complete documentation index, see [llms.txt](https://docs.clearfeed.ai/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clearfeed.ai/api/quick-start/mcp-server.md).

# MCP Server

ClearFeed offers a local **MCP (Model Context Protocol) server** that wraps ClearFeed's External REST APIs and exposes them as MCP tools. This allows agents and MCP-compatible clients such as Codex, Claude Code, or Cursor to work with ClearFeed using tool calls instead of raw HTTP requests.

## When to use the MCP server

Use the MCP server when you want an AI agent to:

* Search or list requests
* Read or update request details
* Post messages to a request
* Create requests
* Look up customers, teams, collections, or custom fields
* Link external tickets to requests
* Generate custom reports based on the Insights API

## Requirements

You will need:

* **Node.js 20+**
* A **ClearFeed Personal Access Token**
* A **ClearFeed API base URL**, typically `https://api.clearfeed.app`

For token setup, see:

{% content-ref url="/pages/UEqFn5bGL2oGo7vYrbGe" %}
[Authentication Guide](/api/quick-start/authentication-guide.md)
{% endcontent-ref %}

## Environment variables

| Variable                 | Required | Description                          |
| ------------------------ | -------- | ------------------------------------ |
| `CLEARFEED_API_BASE_URL` | Yes      | Base URL for ClearFeed External APIs |
| `CLEARFEED_API_TOKEN`    | Yes      | Bearer token used for authentication |
| `DEBUG`                  | No       | Set to `true` to log request timing  |

## Local setup

1. Clone the [ClearFeed MCP repository](https://github.com/clearfeed/clearfeed-mcp)
2. Install dependencies:

```bash
npm install
```

3. Build the server:

```bash
npm run build
```

## Client configuration examples

### Codex

```bash
codex mcp add clearfeed-external \
  --env CLEARFEED_API_BASE_URL=https://api.clearfeed.app \
  --env CLEARFEED_API_TOKEN=your_token \
  -- node /path/to/clearfeed-mcp/dist/index.js
```

Or configure it in `~/.codex/config.toml`:

```toml
[mcp_servers.clearfeed-external]
command = "node"
args = ["/path/to/clearfeed-mcp/dist/index.js"]
env = { CLEARFEED_API_BASE_URL = "https://api.clearfeed.app", CLEARFEED_API_TOKEN = "your_token" }
```

### Claude Code

```bash
claude mcp add clearfeed-external \
  --transport stdio \
  --env CLEARFEED_API_BASE_URL=https://api.clearfeed.app \
  --env CLEARFEED_API_TOKEN=your_token \
  -- node /path/to/clearfeed-mcp/dist/index.js
```

### Claude Desktop

```json
{
  "mcpServers": {
    "clearfeed-external": {
      "command": "node",
      "args": ["/path/to/clearfeed-mcp/dist/index.js"],
      "env": {
        "CLEARFEED_API_BASE_URL": "https://api.clearfeed.app",
        "CLEARFEED_API_TOKEN": "your_token"
      }
    }
  }
}
```

## Available tool groups

| Area          | MCP tools                                                                                                         |
| ------------- | ----------------------------------------------------------------------------------------------------------------- |
| Requests      | `requests_search`, `requests_list`, `requests_get`, `requests_create`, `requests_update`, `requests_post_message` |
| Customers     | `customers_list`, `customers_search`, `customers_get`, `customers_create`, `customers_update`                     |
| Collections   | `collections_list`, `collections_add_channels`                                                                    |
| Channels      | `channels_update`, `channels_delete`                                                                              |
| Custom Fields | `custom_fields_list`, `custom_fields_create`, `custom_fields_update`, `custom_fields_delete`                      |
| Teams         | `teams_list`, `teams_get`                                                                                         |
| Tickets       | `tickets_get_form`, `tickets_link`                                                                                |
| Insights      | `insights_query`                                                                                                  |

## Example use cases

### Example 1: Search and summarize requests

An agent can use `requests_search` or `requests_list` to find recent support conversations, then summarize key issues for a responder or manager.

### Example 2: Update a request

An agent can use:

1. `requests_get` to inspect a request
2. `requests_post_message` to add a message to the request
3. `requests_update` to change fields such as state, assignee, priority, or custom field values

### Example 3: Run support analytics

An agent can call `insights_query` to fetch request counts, response-time metrics, SLA breach metrics, or breakdowns by fields such as assignee, customer, priority, channel, or collection.