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.

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

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:

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

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

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

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:

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

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:

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

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