Front MCP
Use Front from any MCP-compatible client. Search conversations, manage contacts, send messages, tag, assign, and automate inbox workflows — 26 tools, 172 actions.
Quick Start
-
Get a Front API token from Settings > Developers > API tokens.
-
Add to your Claude Code settings (
~/.claude/settings.json):
{
"mcpServers": {
"front": {
"command": "npx",
"args": ["-y", "@houst-com/front-mcp"],
"env": {
"FRONT_API_TOKEN": "your-front-api-token"
}
}
}
}
- Start Claude Code. The Front tools are now available.
Example Workflows
Search for a conversation:
"Search Front conversations about billing issues"
Inspect a thread:
"Get the messages in conversation cnv_abc123"
Manage contacts:
"List contacts and find the one with email alice@example.com"
Tag and assign:
"Tag conversation cnv_abc123 with 'urgent' and assign it to teammate tea_xyz"
Draft a reply:
"Create a draft reply to conversation cnv_abc123 saying we'll follow up tomorrow"
OAuth Setup (Recommended)
OAuth provides automatic token refresh and better security than API tokens.
- Create a Front app at Settings > Developers > OAuth apps.
- Set the redirect URI to
https://localhost:9876/callback. - Enable the resource permissions your MCP server needs (Read, Write, Delete, Send).
- Save the app — copy the Client ID from the OAuth feature (not the App secret from Settings).
- Create
~/.front-mcp/config.json:
{
"auth": {
"method": "oauth",
"oauth": {
"client_id": "your-client-id",
"client_secret_env": "FRONT_MCP_OAUTH_SECRET",
"redirect_port": 9876,
"scopes": []
}
}
}
- Configure Claude Code:
{
"mcpServers": {
"front": {
"command": "npx",
"args": ["-y", "@houst-com/front-mcp"],
"env": {
"FRONT_MCP_AUTH_METHOD": "oauth",
"FRONT_MCP_OAUTH_SECRET": "your-oauth-client-secret"
}
}
}
}
- Run
npx @houst-com/front-mcp authto authenticate (opens browser). - Tokens are encrypted and stored locally (AES-256-GCM, 0600 permissions).
Auth CLI
front-mcp auth # Start OAuth flow
front-mcp auth --status # Check auth state (no token values shown)
front-mcp auth --clear # Remove stored tokens
front-mcp --version # Show version
front-mcp --help # Show usage
Front Permissions
The MCP server needs Front API permissions matching the actions you want to use:
| Permission | Required for |
|---|---|
| Read | All list/get/search actions |
| Write | create, update, assign, add, merge, reply |
| Delete | delete, remove actions |
| Send | messages.create, messages.reply |
For OAuth, configure these in your Front app under Features > OAuth > Resource permissions. For API tokens, permissions are set when creating the token.
Tools Reference
| Tool | Actions |
|---|---|
accounts | list, get, create, update, delete, list_contacts, add_contact, remove_contact |
analytics | create_export, get_export, create_report, get_report |
channels | list, get, update, validate, create, list_for_teammate, list_for_team |
comments | list, get, create, update, list_mentions, reply |
contact_groups | list, create, delete, list_contacts, add_contacts, remove_contacts |
contact_lists | list, create, delete, list_contacts, add_contacts, remove_contacts |
contact_notes | list, create |
contacts | list, get, create, update, delete, merge, list_conversations, add_handle, remove_handle |
conversations | list, get, search, create, update, delete, assign, list_events, list_followers, add_followers, remove_followers, list_inboxes, add_link, remove_links, list_messages, update_reminders, add_tag, remove_tag |
custom_fields | list_for_accounts, list_for_contacts, list_for_conversations, list_for_inboxes, list_for_links, list_for_teammates |
drafts | list, create, create_reply, update, delete |
events | list, get |
inboxes | list, get, create, list_channels, list_conversations, list_access, grant_access, revoke_access |
knowledge_bases | list, get, create, update, list_categories, list_articles, get_article, create_article, update_article, delete_article, get_category, create_category, update_category, delete_category |
links | list, get, create, update, list_conversations |
message_template_folders | list, get, create, update, delete, list_children, create_child |
message_templates | list, get, create, update, delete |
messages | get, create, reply, import, receive_custom, get_seen_status, mark_seen |
rules | list, get, list_for_teammate, list_for_team |
shifts | list, get, create, update, list_teammates, add_teammates, remove_teammates |
signatures | list, get, update, delete, create_for_teammate, create_for_team |
tags | list, get, create, update, delete, list_children, create_child, list_conversations |
teammate_groups | list, get, create, update, delete, list_inboxes, add_inboxes, remove_inboxes, list_teammates, add_teammates, remove_teammates, list_teams, add_teams, remove_teams |
teammates | list, get, update, list_conversations, list_inboxes |
teams | list, get, add_teammates, remove_teammates |
token_identity | get |
See docs/TOOL_REFERENCE.md for the complete reference with policy tiers per action.
Policy Engine
Every action is classified into a tier with a default decision:
| Tier | Default | Examples |
|---|---|---|
read | allow | list, get, search |
write | confirm | create, update, assign |
destructive | deny | delete, remove |
Write actions require a two-step confirmation: the first call returns a prompt, the second call with confirm: true executes. Destructive actions are denied by default.
Custom Policy
Create ~/.front-mcp/policy.json:
{
"defaults": {
"read": "allow",
"write": "allow",
"destructive": "confirm"
},
"overrides": [
{ "tool": "conversations", "action": "delete", "decision": "deny" },
{ "tool": "tags", "action": "*", "decision": "allow" }
]
}
Override precedence: specific action > tool wildcard > tier default.
Security Model
- HTTPS enforced — no HTTP fallback, ever
- Token encryption — AES-256-GCM with PBKDF2 key derivation
- File permissions — token file is 0600 (owner read/write only)
- Output sanitization — configurable field redaction before LLM sees data
- Log redaction — sensitive fields redacted from all log output
- Policy engine — destructive actions denied by default, write actions require confirmation
- No secrets in stdout — stdout is reserved for MCP protocol only
- Minimal dependencies — native fetch, Node.js crypto, pinned exact versions
Environment Variables
| Variable | Required | Description |
|---|---|---|
FRONT_API_TOKEN | Yes (unless OAuth) | Front API token |
FRONT_MCP_AUTH_METHOD | No | oauth or api_token (default: api_token) |
FRONT_MCP_OAUTH_SECRET | Yes (if OAuth) | OAuth client secret |
FRONT_MCP_LOG_LEVEL | No | error, warn, info, debug (default: info) |
FRONT_MCP_POLICY_FILE | No | Path to custom policy JSON file |
Limitations
- stdio transport only — no HTTP/SSE transport in v1 (planned for future)
- Single Front account — one account per server instance
- No webhook support — outbound API calls only, no inbound event processing
- No caching — every request hits the Front API (relies on Front's freshness)
- Attachments — file upload/download not supported in v1
- Application channels — channel-specific message sync endpoints not supported
Development
git clone https://github.com/wearehoust/front-mcp.git
cd front-mcp
npm install
npm test # 519 tests
npm run lint # ESLint strict
npm run type-check # TypeScript strict
npm run build # Compile to dist/
Testing
npm test # Unit + integration tests
npm run test:watch # Watch mode
npm run test:coverage # Coverage report
npm run smoke # Smoke test (builds, starts, verifies 26 tools)
The project includes 519 unit/integration tests and a 172-action live API test script (scripts/live-test-full.js).
Release Process
- Update version in
package.jsonandserver.json - Update
CHANGELOG.md - Commit:
git commit -m "chore: release vX.Y.Z" - Tag:
git tag vX.Y.Z - Push:
git push origin main --tags - GitHub Actions publishes to npm (requires
NPM_TOKENsecret) - Publish to MCP Registry:
mcp-publisher publish
Security
See SECURITY.md for vulnerability reporting.
Contributing
See CONTRIBUTING.md for setup, code standards, and PR process.
License
MIT