Front MCP

io.github.wearehoustPublished by GitHub account wearehoustv1.0.1Updated Oct 24, 2026

MCP server for Front: conversations, contacts, messages, tags, and inbox workflows.

VerifiedSTDIODesktop onlyProductivity & WorkflowCommunication & CollaborationBusiness & Commerce

Overview

AI-generated overview

Lets an assistant work with Front customer conversations, contacts, messages, tags, and inbox workflows through 26 tools and 172 actions.

What you can do
Connects an MCP client to Front's API so the assistant can search and read conversations, inspect messages, list and manage contacts, tags, inboxes, teammates, and knowledge bases, and create drafts or send replies. Actions are grouped into tools such as conversations, contacts, messages, tags, drafts, and analytics. A policy engine classifies each action as read, write, or destructive, with write actions requiring a two-step confirmation and destructive actions denied by default.
When to use it
Useful when a team already runs Front for shared inboxes and support and wants an assistant to look up conversations, summarize threads, manage contacts and tags, or draft replies without leaving the chat client. It fits support and operations workflows rather than general web or file tasks.
Requirements
Runs locally over stdio via the npm package @houst-com/front-mcp, so Node.js and npx are needed. A Front account is required, authenticated either with an API token in FRONT_API_TOKEN or through OAuth using FRONT_MCP_AUTH_METHOD and FRONT_MCP_OAUTH_SECRET, with an OAuth app and redirect URI configured in Front. Front permissions (Read, Write, Delete, Send) must match the actions used. Desktop only; no HTTP or SSE transport.
Before you install
The server holds credentials that grant access to real customer conversations: FRONT_API_TOKEN or FRONT_MCP_OAUTH_SECRET, stored encrypted locally. Write actions create, update, assign, or send messages and require confirmation; destructive actions such as delete or remove are denied by default but can be allowed through a custom policy file. Sending replies and importing messages act on live Front data, and conversation content is passed to the model provider. Attachments are not supported in…

Installation

In SourceWeft

  1. Open Front MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Front MCP

[CI] [npm] [License: MIT] [Node] [TypeScript] [MCP] [Front API]

Use Front from MCP clients that support local stdio servers. Search conversations, manage contacts, send messages, tag, assign, and automate inbox workflows — 26 tools, 172 actions.

Quick Start

  1. Get a Front API token from Settings > Developers > API tokens.

  2. Add this server to the top-level mcpServers object in your Claude Code user configuration (~/.claude.json), preserving any existing settings and servers. For a shared project configuration, use .mcp.json instead. See Claude Code's MCP configuration guide.

json
{  "mcpServers": {    "front": {      "command": "npx",      "args": ["-y", "@houst-com/front-mcp"],      "env": {        "FRONT_API_TOKEN": "your-front-api-token"      }    }  }}
  1. Start Claude Code. The Front tools are now available.

Node.js 20 or newer is required. The server runs locally using your own Front credentials; no Houst-hosted service is required. Keep API tokens out of version control; shared .mcp.json files should use "FRONT_API_TOKEN": "${FRONT_API_TOKEN}" and set that variable in the environment that launches Claude Code.

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 [email protected]"

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.

  1. Create a Front app at Settings > Developers > OAuth apps.
  2. Set the redirect URI to https://localhost:9876/callback.
  3. Enable the resource permissions your MCP server needs (Read, Write, Delete, Send).
  4. Save the app — copy the Client ID from the OAuth feature (not the App secret from Settings).
  5. Create ~/.front-mcp/config.json:
json
{  "auth": {    "method": "oauth",    "oauth": {      "client_id": "your-client-id",      "client_secret_env": "FRONT_MCP_OAUTH_SECRET",      "redirect_port": 9876,      "scopes": []    }  }}
  1. Configure Claude Code:
json
{  "mcpServers": {    "front": {      "command": "npx",      "args": ["-y", "@houst-com/front-mcp"],      "env": {        "FRONT_MCP_AUTH_METHOD": "oauth",        "FRONT_MCP_OAUTH_SECRET": "your-oauth-client-secret"      }    }  }}
  1. Run npx @houst-com/front-mcp auth to authenticate (opens browser).
  2. Tokens are encrypted and stored locally (AES-256-GCM, 0600 permissions).

Auth CLI

bash
front-mcp auth            # Start OAuth flowfront-mcp auth --status   # Check auth state (no token values shown)front-mcp auth --clear    # Remove stored tokensfront-mcp --version       # Show versionfront-mcp --help          # Show usage

Front Permissions

The MCP server needs Front API permissions matching the actions you want to use:

PermissionRequired for
ReadAll list/get/search actions
Writecreate, update, assign, add, merge, reply
Deletedelete, remove actions
Sendmessages.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

ToolActions
accountslist, get, create, update, delete, list_contacts, add_contact, remove_contact
analyticscreate_export, get_export, create_report, get_report
channelslist, get, update, validate, create, list_for_teammate, list_for_team
commentslist, get, create, update, list_mentions, reply
contact_groupslist, create, delete, list_contacts, add_contacts, remove_contacts
contact_listslist, create, delete, list_contacts, add_contacts, remove_contacts
contact_noteslist, create
contactslist, get, create, update, delete, merge, list_conversations, add_handle, remove_handle
conversationslist, 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_fieldslist_for_accounts, list_for_contacts, list_for_conversations, list_for_inboxes, list_for_links, list_for_teammates
draftslist, create, create_reply, update, delete
eventslist, get
inboxeslist, get, create, list_channels, list_conversations, list_access, grant_access, revoke_access
knowledge_baseslist, get, create, update, list_categories, list_articles, get_article, create_article, update_article, delete_article, get_category, create_category, update_category, delete_category
linkslist, get, create, update, list_conversations
message_template_folderslist, get, create, update, delete, list_children, create_child
message_templateslist, get, create, update, delete
messagesget, create, reply, import, receive_custom, get_seen_status, mark_seen
ruleslist, get, list_for_teammate, list_for_team
shiftslist, get, create, update, list_teammates, add_teammates, remove_teammates
signatureslist, get, update, delete, create_for_teammate, create_for_team
tagslist, get, create, update, delete, list_children, create_child, list_conversations
teammate_groupslist, get, create, update, delete, list_inboxes, add_inboxes, remove_inboxes, list_teammates, add_teammates, remove_teammates, list_teams, add_teams, remove_teams
teammateslist, get, update, list_conversations, list_inboxes
teamslist, get, add_teammates, remove_teammates
token_identityget

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:

TierDefaultExamples
readallowlist, get, search
writeconfirmcreate, update, assign
destructivedenydelete, 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:

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

VariableRequiredDescription
FRONT_API_TOKENYes (unless OAuth)Front API token
FRONT_MCP_AUTH_METHODNooauth or api_token (default: api_token)
FRONT_MCP_OAUTH_SECRETYes (if OAuth)OAuth client secret
FRONT_MCP_LOG_LEVELNoerror, warn, info, debug (default: info)
FRONT_MCP_POLICY_FILENoPath 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

bash
git clone https://github.com/wearehoust/front-mcp.gitcd front-mcpnpm installnpm test          # 519 testsnpm run lint      # ESLint strictnpm run type-check # TypeScript strictnpm run build     # Compile to dist/

Testing

bash
npm test              # Unit + integration testsnpm run test:watch    # Watch modenpm run test:coverage # Coverage reportnpm 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

  1. Update package.json and package-lock.json with npm version X.Y.Z --no-git-tag-version. Update both version fields in server.json, the server version in src/server.ts, and CHANGELOG.md.
  2. Confirm npm trusted publishing is configured for wearehoust/front-mcp and the release.yml workflow. The release workflow uses GitHub OIDC for npm and the MCP Registry.
  3. Run npm ci, lint, type-check, tests, build, and smoke. Check the packed npm artifact and its MCP handshake version.
  4. Commit as chore: release vX.Y.Z, open a PR, and merge after CI and review pass.
  5. Fetch main and create an annotated vX.Y.Z tag on the verified release commit. Push only that tag with git push origin refs/tags/vX.Y.Z.
  6. GitHub Actions verifies version metadata, runs the checks, publishes the npm package, and then publishes server.json to the MCP Registry in a separate job. Registration retries briefly when the registry cannot yet see the new npm version.
  7. Verify both registries report the new version and smoke-test the published npm package.

If npm publication succeeds but registry registration fails, use Re-run failed jobs to retry only the registry job. For recovery of an older release (including workflows that used a single publish job), open Actions → Release → Run workflow on main and enter the existing tag, such as v1.1.1. This manual action only registers the tagged server.json; it never republishes npm or changes the tag. The recovery workflow must first be merged into main.

Security

See SECURITY.md for vulnerability reporting.

Contributing

See CONTRIBUTING.md for setup, code standards, and PR process.

License

MIT

Source: README.md at commit 0151928

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts