@clearfeed-ai/mcp

The official ClearFeed MCP server. Exposes the ClearFeed REST API as Model Context Protocol tools so any spec-conformant host (Claude.ai, Claude Code, Cursor, Cline, Goose, ChatGPT, …) can drive ClearFeed.

There are three ways to use this package:

1. Connect via any MCP host (recommended) — point your host at the hosted ClearFeed MCP URL.
2. Run locally over stdio — for development, audit, or self-host.
3. Embed createMcpServer in your own server — for advanced integrations.

1. Connect via any MCP host

In your MCP host's "Add custom connector" / "Add MCP server" dialog, enter:

https://mcp.clearfeed.app/mcp

The host will open a browser to authorize the connection. Sign in to your ClearFeed account and approve.

The connector is scoped to a single ClearFeed Account. To use it with a different Account, sign in to that Account and add a new connector.

2. Local stdio (development / self-host)

Get a developer token at https://web.clearfeed.app/settings/developer-settings.

npx @clearfeed-ai/mcp

Configure via env:

| Variable | Default | Description | |---|---|---| | CLEARFEED_API_TOKEN | (required) | Developer token from settings | | CLEARFEED_API_BASE_URL | https://api.clearfeed.app | Override for self-hosted / staging | | DEBUG | false | Set to true to log request timing |

Claude Code

claude mcp add clearfeed \
  --transport stdio \
  --env CLEARFEED_API_TOKEN=your_token \
  -- npx -y @clearfeed-ai/mcp

Or in .mcp.json:

{
  "mcpServers": {
    "clearfeed": {
      "command": "npx",
      "args": ["-y", "@clearfeed-ai/mcp"],
      "env": { "CLEARFEED_API_TOKEN": "your_token" }
    }
  }
}

Claude Desktop

In claude_desktop_config.json:

{
  "mcpServers": {
    "clearfeed": {
      "command": "npx",
      "args": ["-y", "@clearfeed-ai/mcp"],
      "env": { "CLEARFEED_API_TOKEN": "your_token" }
    }
  }
}

Codex

codex mcp add clearfeed \
  --env CLEARFEED_API_TOKEN=your_token \
  -- npx -y @clearfeed-ai/mcp

Or in ~/.codex/config.toml:

[mcp_servers.clearfeed]
command = "npx"
args = ["-y", "@clearfeed-ai/mcp"]
env = { CLEARFEED_API_TOKEN = "your_token" }

3. Embed createMcpServer in your own server

import { createMcpServer } from '@clearfeed-ai/mcp';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';

const server = createMcpServer({
  baseUrl: 'https://api.clearfeed.app',
  accountToken,        // ClearFeed developer token
  accountUuid,         // optional
});

const transport = new StreamableHTTPServerTransport({ /* ... */ });
await server.connect(transport);

Tools

| Area | MCP tools and ClearFeed REST endpoints | | --- | --- | | 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 | | Users | users_list | | Tickets | tickets_get_form, tickets_link | | Insights | insights_query (supports Requests.customer_id, Requests.customer_owner dimensions) |

tools/list against any deployment returns the live, source-of-truth schema.

Local development

git clone https://github.com/clearfeed/clearfeed-mcp.git
cd clearfeed-mcp
npm install
cp .env.example .env  # set CLEARFEED_API_TOKEN
npm run build
npm run dev           # tsx src/index.ts (stdio)

Notes

• Attachment support is intentionally not implemented in v1.
• File-based debug logs go to stderr to keep stdout clean for the JSON-RPC framing.