Skip to content

About

MCP server exposing FirstReply customer support operations as tools for AI assistants like Claude

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

FirstReply MCP Server

MCP (Model Context Protocol) server that exposes FirstReply customer support operations as tools for AI assistants like Claude. It lets an assistant browse and answer customer conversations, look up contacts, search and maintain the knowledge base, draft and translate replies, draft and schedule social media posts, manage classifications, templates, prompts, webhooks and saved filters, pull support and publishing statistics and manage organization API keys, all scoped and permission-checked by the FirstReply REST API.

The server speaks MCP protocol 2026-07-28 and the earlier 2025-* revisions over stdio and HTTP, built on the v2 MCP TypeScript SDK.

Tools

Tools are named resource_action. Every organization-scoped tool takes an organizationId (see organization_list). Tools that send something to a customer or delete data are annotated as destructive.

Organization, members & API keys

Tool Description
organization_list List accessible organizations
organization_get Get an organization with its settings and AI prompts
organization_update Update name, language, auto-close and the custom AI prompts
organization_usage Plan, trial state and channel / member counts against the limits
member_list List organization members
member_get Get one member
member_create Invite a member by email with a permission level (signed-in account only)
member_update Change a member's permission level (signed-in account only)
member_delete Remove a member (destructive, signed-in account only)
api_key_list List the organization's named API keys (metadata only)
api_key_create Create a named API key; plaintext returned once (signed-in account only)
api_key_delete Delete (revoke) an API key (destructive, signed-in account only)

Channels

Tool Description
channel_list List the channels (email, website chat, WhatsApp, Facebook Page, Instagram, LinkedIn, Threads, X, TikTok, YouTube, Google Business Profile, Bluesky, Mastodon, Telegram, Google Play, App Store) and whether Publishing is on
channel_get Get one channel
channel_statistics Statistics per channel
channel_refresh Fetch new messages from a channel now
channel_test Test the connection of a channel to its platform
channel_create Create a channel from settings or credentials: email, website chat, Bluesky, Telegram, App Store, Google Play
channel_connect Start connecting (or reconnecting) an account that signs in on the platform; returns the login link
channel_update Rename, pause, turn Publishing and comment handling on or off, change settings or credentials
channel_playstore_service_account The organization's Google service account to invite in the Play Console
channel_tiktok_creator_info What a TikTok channel may post right now (privacy levels, interactions, video length)

Facebook Pages, Instagram, LinkedIn, WhatsApp, Threads, X, TikTok, YouTube, Google Business Profile and Mastodon are connected by signing in on the platform. channel_connect returns the login link; the user opens it in a browser where they are signed in to FirstReply (as the organization's owner, which an API key acts as) and finishes there. The link is valid for 10 minutes. There is no tool to delete a channel.

Conversations & messages

Tool Description
conversation_list List / filter / search conversations (status, channel, member, contact, classification, language, spam, priority, date ranges, search operators)
conversation_get Get one conversation
conversation_thread Get a conversation with all of its messages
conversation_messages List the messages of a conversation
conversation_reply Send a reply to the customer, or store an internal note or a draft, with attachments (destructive)
conversation_close Close a conversation
conversation_read Mark a conversation as read
conversation_spam Mark a conversation as spam or not spam
conversation_update Assign, reprioritize, reclassify, rename, change language, contact or spam flag
conversation_delete Delete a conversation (destructive)
conversation_stats Conversation statistics for a date range
conversation_stats_by_member Statistics per member for a date range
conversation_metrics Response and resolution metrics for a date range
conversation_totals Current open / unread totals
message_get Get one message
message_update Edit a draft or internal note
message_send Send a draft (destructive)
message_delete Delete a message (destructive)
attachment_upload Upload a file from a public https address; returns the attachment for conversation_reply

The search argument of conversation_list, search and the saved filters understands the FirstReply search syntax: words are AND-ed and prefix matched, "quoted phrases", -word, and the operators from:, subject:, is: (open, closed, unread, read, assigned, unassigned, ai), has: (attachment, draft), before: and after: (YYYY-MM-DD).

attachment_upload takes images (JPEG, PNG, GIF, WebP), PDF, plain text, CSV, Word and Excel files of up to 50 MB. Like post_media_upload it only fetches public https addresses, and the file is streamed to the API, not kept.

Contacts

Tool Description
contact_list List / search contacts
contact_get Get one contact with custom fields
contact_create Create a contact
contact_update Update a contact
contact_delete Delete a contact (destructive)
contact_field_list List the custom contact fields

Social posts

Tool Description
post_list List / filter posts (status, channel, period, text); order: asc for upcoming posts
post_get Get a post with its channels, publish state and latest metrics
post_statistics How many posts are drafts, waiting for approval, scheduled, published and failed, and when the next one goes out
post_metrics Metric snapshots of every channel of a published post
post_comments The comment threads on a post, as conversations
post_write Write, shorten or rewrite a post text with AI, for a platform and a character limit; saves nothing
post_media_upload Upload an image or video from a public https address; returns the media id for a post
post_create Save a post as a draft, with media and per-channel text and settings
post_schedule Schedule a new post or an existing draft for a time on the given channels
post_reschedule Move a post to another time; text, channels and media stay
post_analytics Totals, daily series, top posts and channels for a period

Posts target channels with Publishing on (publishingEnabled in channel_list), given as channelIds or as targets with a text of their own and the platform's settings (YouTube title and made-for-kids choice, TikTok privacy level, Instagram post type, X thread parts, ...). There is no tool to publish right away, approve, retry or delete a post: a public post cannot be taken back, so the assistant drafts or schedules and a person can still change it. Scheduled times have to be at least 10 minutes ahead. When the organization requires approval, a member's scheduled post waits for a manager (status PENDING_APPROVAL); such a post is not rescheduled with manager rights (an API key acts as the owner), since saving it would approve it. Comments are only read: hiding, deleting or liking a comment and answering it privately act publicly on the platform and stay in FirstReply.

Classifications

Tool Description
classification_list List classifications with their automation settings
classification_get Get one classification
classification_create Create a classification
classification_update Update a classification (unchanged settings are kept)
classification_delete Delete a classification, optionally moving its conversations (destructive)
classification_impact Preview what deleting a classification affects
classification_statistics Conversation counts per classification

Knowledge base

Tool Description
knowledge_search Search or browse knowledge entries
knowledge_get Get one knowledge entry
knowledge_create Add a question / answer entry
knowledge_update Update a knowledge entry
knowledge_delete Delete a knowledge entry (destructive)
knowledge_source_list List synced knowledge sources with their sync state
knowledge_source_get Get one knowledge source
knowledge_source_create Add a website or helpdesk (Freshdesk) source
knowledge_source_update Rename a source, change its settings or its sync
knowledge_source_delete Delete a knowledge source (destructive)
knowledge_source_sync Start a sync now
knowledge_source_status Sync status of a source

Knowledge source configurations hold credentials and are never returned. knowledge_source_update puts the settings it is given on top of the stored ones. GitHub, Notion, GitBook, ClickUp and monday.com sources are connected by signing in and are added in FirstReply; their settings can be changed here.

AI & search

Tool Description
ai_draft_reply Generate an AI reply draft for a conversation without sending it
ai_prompt Run a free-form prompt with the organization's persona and knowledge
ai_translate Translate a text, e.g. a reply into the customer's language
ai_test Simulate an incoming message: classification, spam verdict and reply
search Global search across conversations, contacts, knowledge and messages

Templates, prompts, webhooks & filters

Tool Description
template_list / template_get / template_create / template_update / template_delete Reply templates and their language variants
prompt_list / prompt_get / prompt_create / prompt_update / prompt_delete Saved AI prompts
webhook_list / webhook_get / webhook_create / webhook_update / webhook_delete Webhooks and their events (including post.create, post.update, post.delete)
webhook_test Send a test event to a webhook
webhook_rotate_secret Generate a new signing secret (returned once)
filter_list / filter_get / filter_create / filter_update / filter_delete Saved conversation filters

Not covered, by design: authentication and profile endpoints, channel creation and OAuth connections, knowledge source creation, billing, attachments and CSV import / export, publishing posts right away, approving posts, media uploads, comment moderation and private replies to comments. Those stay in the FirstReply web app.

Widgets

Hosts that support MCP Apps (Claude, ChatGPT) show some results as a small view next to the answer:

Widget Tools What it shows
ConversationList conversation_list Contact, subject, last message, status and classification per conversation
ReplyDraft ai_draft_reply The draft in a text field, with Send reply, Save as draft and Copy
PostCard post_get, post_create, post_schedule, post_reschedule The post, its time and the status per channel
PostAnalytics post_analytics Totals, views per day and numbers per channel
ResultCard conversation_reply, conversation_close, channel_connect, channel_create, channel_update A confirmation, or the sign-in link of a channel

Send reply in ReplyDraft calls conversation_reply with the text on screen; a host that does not let widgets call tools only offers Copy. Widgets are in English and German, following the host's language. Other hosts ignore them and get the same JSON text as before.

Requirements

  • Node.js >= 20
  • A FirstReply account, or an organization API key

Authentication

The hosted server accepts two kinds of bearer token:

  • Sign-in (OAuth 2.1): hosts such as Claude and ChatGPT only need the address https://mcp.firstreply.ai/. They register themselves, send the user to FirstReply to allow the connection, and act with that user's permissions in all of their organizations.
  • Organization API key: as described below; the only option for the local (stdio) server.

With an API key, the server authenticates against the FirstReply REST API with an organization API key (fr_...), created in FirstReply under Organization → Development → API Keys. Organizations support multiple named keys with optional expiry, so it is best to create a dedicated key for this MCP server. The key is sent as Authorization: Bearer.

API key requests run with the permissions of the organization owner: treat the key as a secret and rotate it by creating a new key and deleting the old one (in FirstReply, signed in). A key works with the organization's data, not with the account itself: it cannot invite, change or remove members, create or delete API keys, delete the organization or open the billing portal. Those tools need the account sign-in.

A key only reaches its own organization: organization_list returns just that organization, and requests for any other organization are refused with 403. To work across several organizations, configure one server per key.

Usage (stdio, e.g. Claude Desktop)

{
  "mcpServers": {
    "firstreply": {
      "command": "npx",
      "args": ["-y", "@firstreply/mcp"],
      "env": {
        "FIRSTREPLY_API_TOKEN": "fr_..."
      }
    }
  }
}

Claude Code

claude mcp add firstreply --env FIRSTREPLY_API_TOKEN=fr_... -- npx -y @firstreply/mcp

Usage (hosted)

The server runs at https://mcp.firstreply.ai/ (streamable HTTP). Send the organization API key as bearer token:

claude mcp add --transport http firstreply https://mcp.firstreply.ai/ \
  --header "Authorization: Bearer fr_..."

Usage (HTTP)

npm run build && npm run start:http   # listens on :8080

Stateless: every request gets its own server instance, 2026-07-28 requests are answered directly and 2025-era clients over a stateless streamable-HTTP transport. Every request must carry Authorization: Bearer with an API key or access token. A /health endpoint is provided for probes.

Without a token the answer is 401 with a WWW-Authenticate header naming /.well-known/oauth-protected-resource, where the sign-in of an MCP host starts; MCP_SERVER_URL is the address the server names itself with there.

A browser that opens the endpoint (GET / with Accept: text/html) gets the landing page from public/.

Environment variables

Variable Description
FIRSTREPLY_API_TOKEN Organization API key (stdio mode)
FIRSTREPLY_API_URL API base URL (default https://api.firstreply.ai)
MCP_SERVER_URL Public address of the HTTP server, its OAuth resource identifier (default https://mcp.firstreply.ai)
PORT HTTP port (HTTP mode, default 8080)
MCP_ENDPOINT_PATH HTTP endpoint path (default /)

Development

npm install
npm run typecheck
npm test          # builds and runs node:test suites
npm run build     # compiles TypeScript to dist/

Project structure

src/
├── index.ts              # stdio entry point
├── http-server.ts        # HTTP entry point (Express + createMcpHandler)
├── server.ts             # MCP server factory (McpServer + registerTool)
├── tools.ts              # loads the tool modules, exposes the registry
├── tools/registry.ts     # add() builder, schema helpers, dispatch
├── tools/<resource>.ts   # one module per resource (conversations, contacts, ...)
├── media.ts              # fetches a public file and streams it to a signed upload URL
└── client.ts             # minimal FirstReply REST client
test/
├── tools.test.ts         # tool definition checks and handler tests against a fake client
└── protocol.test.ts      # stdio and HTTP end to end, both protocol eras, against an API stub

Adding a tool: call add(name, description, zodShape, annotations, handler) in the matching src/tools/<resource>.ts. The zod shape is validated by the SDK and published to clients as JSON Schema; every argument needs a description (the tests check).

About

MCP server exposing FirstReply customer support operations as tools for AI assistants like Claude

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages