MCPhoenix

MCPhoenix is an Elixir/Phoenix-based MCP server that implements the Model Context Protocol to enable AI models to interact with application data and services through a unified interface. It exposes real-time notifications via Server-Sent Events (SSE) and a JSON-RPC endpoint for client requests. The server also includes a simple resource system, an event publish/subscribe mechanism, and integrations for Flux image generation and Dart task management, all designed to work in a distributed, self-healing architecture leveraging Cloudflare Durable Objects and Workers. Use the SSE stream to receive live updates and the JSON-RPC endpoint to perform actions or query state.

You can access the MCP endpoints once the server is running: the SSE stream is available at the /mcp/stream path and the JSON-RPC endpoint is at /mcp/rpc. The system is designed to support multiple MCP servers configured in priv/config/mcp_servers.json, and it can automatically manage those servers at startup. The Cloudflare integration enables edge-backed durability and automatic recovery, making the architecture resilient to partial outages.

Prerequisites:

• Elixir 1.14 or higher
• Erlang 25 or higher
• Phoenix 1.7.0 or higher
• Python 3.9+ (for Flux and Dart integration)
• Node.js 18+ (for optional Dart MCP integration)
• Cloudflare account (for Durable Objects integration)

Installation steps:

1. Clone the repository and install dependencies:

git clone https://github.com/yourusername/mcpheonix.git
cd mcpheonix
mix deps.get

2. Configure Cloudflare integration:

• Create and deploy a Cloudflare Worker using the template at cloudflare/durable-objects-worker.js
• Set environment variables (in your deployment):
  • CLOUDFLARE_WORKER_URL: URL of your deployed worker
  • CLOUDFLARE_ACCOUNT_ID: Your Cloudflare account ID
  • CLOUDFLARE_API_TOKEN: API token with Workers and DO permissions

3. Optional Flux integration (for image generation):

• Follow the Flux Integration documentation (docs/flux_integration.md) to configure environment access and credentials

4. Optional Dart integration (for task management):

• Follow the Dart Integration documentation (docs/dart_integration.md) to start the Dart MCP server if you plan to use Dart-related tooling

5. Start the server:

mix phx.server

The server will be available at http://localhost:4001.

6. If you need to customize MCP servers, edit priv/config/mcp_servers.json to define additional servers and their environment.

Tips and notes:

• The MCP endpoints include SSE at GET /mcp/stream and JSON-RPC at POST /mcp/rpc. Client IDs can be provided via the x-mcp-client-id header or will be generated automatically.
• Cloudflare integration enables auto-recovery and state synchronization across edge locations using Durable Objects and Workers; ensure you configure CLOUDFLARE_WORKER_URL, CLOUDFLARE_ACCOUNT_ID, and CLOUDFLARE_API_TOKEN correctly.
• You can add additional MCP servers by configuring priv/config/mcp_servers.json; the application will load and manage these servers on startup.
• If you encounter port or binding issues, verify that the server is started correctly with mix phx.server and ensure your firewall allows traffic to the configured port (default 4001).
• For image generation or Dart tooling, ensure the related services have the necessary dependencies installed and accessible from the MCPhoenix environment.