API & MCP

ClearFeed provides two programmatic ways to manage requests: the REST API for direct integration and the MCP server for AI agent workflows.

---

REST API

ClearFeed's REST API provides comprehensive access to create, search, update, and analyze requests. Build custom integrations, automate workflows, and connect ClearFeed to your existing tools.

What You Can Do

Area	Capabilities
Requests	Create, search, update, post messages, close
Insights	Query response times, SLA metrics, team performance
Customers	Look up and update customer information
Collections	List collections, add channels
Custom Fields	List, create, update, delete custom fields

Getting Started

1. Generate a Personal Access Token from Settings → Developer Settings

2. Choose the token access level that matches your integration:

   • Read-only for lookups, analytics, and reporting-style integrations

   • Read & Write for integrations that create, update, or delete ClearFeed data

3. Use the token in the Authorization: Bearer header for all API requests

4. See Developer Settings for authentication and token-scope details

Full API Reference: ClearFeed API Documentation

---

MCP Server

The MCP (Model Context Protocol) server exposes ClearFeed as a set of tools that AI assistants like Claude, Cursor, and Codex can call. Ask an assistant to find a request, post a reply, or pull an analytics number, and it talks to ClearFeed for you.

ClearFeed offers two recommended ways to connect:

• Remote MCP server at https://mcp.clearfeed.app/mcp. Recommended for most teams; nothing to install or host.

• Local stdio server. Run the npm package with npx @clearfeed-ai/mcp if you prefer to run the server yourself or want to embed it in your own server.

What You Can Do

Area	Example prompts for AI agents
Search requests	"Find all high-priority requests from the last week"
Summarize	"Summarize the open requests assigned to me"
Update requests	"Mark request CF-1234 as in progress and assign to @john"
Post updates	"Reply to request CF-5678 saying we're investigating"
Look up details	"Show me the customer info for request CF-9012"
Analytics	"What's our average response time this month?"
Link tickets	"Link the Jira ticket PROJ-123 to request CF-4567"

Available Tools

Category	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
Tickets	tickets_get_form, tickets_link
Insights	insights_query
Other	Channels, Custom Fields, Teams, Users

---

Remote MCP server

Add https://mcp.clearfeed.app/mcp to your AI assistant once and every user on your team can sign in with their own ClearFeed login. Each user authorizes through OAuth, and ClearFeed handles the API token in the background.

Setup in Claude

Claude supports the remote MCP server through its Custom Connectors. There are two ways to add it.

Option 1: Add it for the whole team (recommended)

A workspace admin can add the connector once and make it available to everyone:

1. Go to https://claude.ai/admin-settings/connectors.

2. Click Add custom connector.

3. Name it ClearFeed and set the URL to https://mcp.clearfeed.app/mcp.

4. Save.

Adding ClearFeed as a custom connector in Claude

Once the connector is published, every member of the workspace will see it in their connector list and can sign in individually.

Option 2: Add it just for yourself

If you do not have admin access, or you want to try it on your own first:

1. Go to https://claude.ai/customize/connectors.

2. Click Add custom connector.

3. Use the same name and URL: ClearFeed and https://mcp.clearfeed.app/mcp.

Signing in

After the connector is added, each user has to complete the OAuth flow once before Claude can call any tool:

1. Open Claude and start a conversation.

2. Pick the ClearFeed connector.

3. Claude opens a browser window where you sign in to ClearFeed and approve access.

Tool calls fail until that flow is finished, so anyone on the team who wants to use ClearFeed in Claude has to do this step on their own login.

Sign in to the ClearFeed account you want to connect. The connector is bound to the account you are active on at the moment you authorize. If you belong to multiple accounts, switch to the one you want to connect in ClearFeed before completing the OAuth flow.

Connecting more than one account

Today a single connector is tied to a single ClearFeed account. If you work across two accounts (for example a parent account and a child account), add the connector twice with different names, like ClearFeed (Parent) and ClearFeed (Child), each pointing at https://mcp.clearfeed.app/mcp. Sign in to the matching ClearFeed account when you authorize each one.

Controlling which tools Claude can run

Claude lets you decide, per tool, whether it runs automatically, asks for approval first, or is turned off entirely. Read-only tools (search, list, get, analytics) default to Always allow and write tools (create, update, link, delete) default to Needs approval, but you can change any of them.

Per-tool permissions for the ClearFeed connector in Claude

Permissions and tokens

Tool calls run against the signed-in user's Personal Access Token. If the user already has one, it gets reused; if not, ClearFeed creates one the first time they authorize the connector. There is nothing to set up by hand.

Every call still respects that user's ClearFeed permissions and token scope. The server exposes the full tool list, but a call only succeeds if the signed-in user can do that action in ClearFeed and their token scope allows it. For example, a user who cannot delete custom fields will see the Delete custom field tool in Claude, but the call will fail. Similarly, write tools such as request updates or message posting require a read/write token.

If a user is later removed from the ClearFeed account, the next tool call from their connector fails and the token is revoked. They will need to be added back to the account and re-authorize the connector to use it again.

---

Local stdio server

If you prefer to run the MCP server yourself, the same tools are available through the @clearfeed-ai/mcp npm package.

1. Set CLEARFEED_API_TOKEN as an environment variable. Generate the token from Settings → Developer Settings.

2. If you use a non-default ClearFeed API endpoint, also set CLEARFEED_API_BASE_URL. The default is https://api.clearfeed.app.

3. Configure your MCP client to start the local server with npx -y @clearfeed-ai/mcp.

For example, a local MCP client configuration can start ClearFeed with:

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

This mode runs with a single API token, so every tool call uses that one user's permissions.

Package documentation: @clearfeed-ai/mcp on npm

---

FAQs

1. How do I get my API token? Answer: Navigate to Settings → Developer Settings and click Generate Token. See Developer Settings.

2. What's the difference between REST API and MCP? Answer: REST API is for direct HTTP-based integration. MCP server wraps the REST API as tools for AI agents to use via the Model Context Protocol.

3. Do I need to create an API token to use the remote MCP server? Answer: No, not by hand. The remote server at mcp.clearfeed.app/mcp uses OAuth. When you authorize the connector, ClearFeed reuses your existing Personal Access Token or creates one for you automatically. You only need to generate a token yourself if you run the local stdio server.

4. Can one connector talk to more than one ClearFeed account? Answer: Not today. A connector is bound to the ClearFeed account you were signed into when you authorized it. To work with multiple accounts, add the connector again under a different name and sign in to the other account during that OAuth flow.

5. A tool shows up in Claude but fails when I run it. Why? Answer: The MCP server exposes the full tool list to every user, but each call still runs against your ClearFeed permissions and token scope. If you do not have access to that feature in ClearFeed, or if your token is read-only and the tool needs to write data, the call will fail. Ask an admin to grant the matching permission or regenerate your token with the required access level.

6. Are webhooks available for real-time updates? Answer: Yes, configure webhooks in Settings → Developer Settings → Events API Subscription.