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