Content
# FirstReply MCP Server
MCP ([Model Context Protocol](https://modelcontextprotocol.io)) server that exposes
[FirstReply](https://firstreply.ai) customer support operations as tools for AI
assistants like Claude. It lets an assistant browse and answer customer
conversations, pull support statistics, draft AI replies, and manage
organization API keys — all scoped and permission-checked by the FirstReply
REST API.
## Tools
### Organization & setup
| Tool | Description |
|------|-------------|
| `organization_list` | List accessible organizations |
| `inbox_list` | List support inboxes of an organization |
| `member_list` | List organization members |
| `api_key_list` | List the organization's named API keys (metadata only) |
| `api_key_create` | Create a named API key; plaintext returned once |
| `api_key_delete` | Delete (revoke) an API key (destructive) |
### Conversations
| Tool | Description |
|------|-------------|
| `conversation_list` | List/filter customer conversations |
| `conversation_get` | Get one conversation |
| `conversation_messages` | List the messages of a conversation |
| `conversation_reply` | Send a reply to the customer (destructive) |
| `conversation_close` | Close a conversation |
| `conversation_update` | Assign / reprioritize / reclassify a conversation |
| `conversation_stats` | Conversation statistics for a date range |
| `conversation_totals` | Current open/unread totals |
### AI
| Tool | Description |
|------|-------------|
| `ai_draft_reply` | Generate an AI reply draft without sending it |
## Requirements
- Node.js >= 18
- A FirstReply organization API key
## Authentication
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.
## Usage (stdio, e.g. Claude Desktop)
```json
{
"mcpServers": {
"firstreply": {
"command": "npx",
"args": ["-y", "@firstreply/mcp"],
"env": {
"FIRSTREPLY_API_TOKEN": "fr_..."
}
}
}
}
```
### Claude Code
```bash
claude mcp add firstreply --env FIRSTREPLY_API_TOKEN=fr_... -- npx -y @firstreply/mcp
```
## Usage (HTTP)
```bash
npm run build && npm run start:http # listens on :8080
```
Stateless streamable-HTTP transport; every request must carry
`Authorization: Bearer fr_...`. A `/health` endpoint is provided for probes.
## Environment variables
| Variable | Description |
|----------|-------------|
| `FIRSTREPLY_API_TOKEN` | Organization API key (stdio mode) |
| `FIRSTREPLY_API_URL` | API base URL (default `https://api.firstreply.ai`) |
| `PORT` | HTTP port (HTTP mode, default 8080) |
| `MCP_ENDPOINT_PATH` | HTTP endpoint path (default `/`) |
## Development
```bash
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 # streamable-HTTP entry point (Express)
├── server.ts # MCP server wiring
├── tools.ts # tool definitions and handlers
└── client.ts # minimal FirstReply REST client
test/
└── tools.test.ts # tool definition sanity checks
```
## License
[MIT](LICENSE)
