Front MCP

Front MCP

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.

{
  "mcpServers": {
    "front": {
      "command": "npx",
      "args": ["-y", "@houst-com/front-mcp"],
      "env": {
        "FRONT_API_TOKEN": "your-front-api-token"
      }
    }
  }
}

3. 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:

{
  "auth": {
    "method": "oauth",
    "oauth": {
      "client_id": "your-client-id",
      "client_secret_env": "FRONT_MCP_OAUTH_SECRET",
      "redirect_port": 9876,
      "scopes": []
    }
  }
}

6. 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"
      }
    }
  }
}

7. Run npx @houst-com/front-mcp auth to authenticate (opens browser).
8. 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

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