MCPheonix

MCPhoenix

MCP server built on Phoenix Framework (Elixir). Exposes Server-Sent Events and JSON-RPC endpoints for MCP clients, with support for managing multiple child MCP servers through JSON configuration.

Note: the module and directory names use the spelling "MCPheonix" (without the 'o') throughout the codebase.

What It Does

Runs a Phoenix web server on port 4001 that:

1. Accepts MCP JSON-RPC requests at POST /mcp/rpc
2. Streams events to clients via SSE at GET /mcp/stream
3. Manages child MCP servers (Flux image generation, Dart task management, etc.) as supervised processes
4. Routes tool calls to the appropriate child server over stdio

Child servers are defined in priv/config/mcp_servers.json and started automatically at boot.

Status

Area	State
Transport	HTTP (SSE + JSON-RPC)
Framework	Phoenix 1.7, Elixir >= 1.14, Erlang >= 25
Child MCP servers	Flux (image generation), Dart (task management)
OTP supervision	Yes — child servers are supervised processes
Cloudflare integration	Durable Objects client (experimental, uses custom hex package)
Event system	Broadway + GenStage for processing pipelines
Tests	ExUnit, 2 test files (Cloudflare DO client, mock websocket)
License	MIT

Architecture

lib/
  mcpheonix/
    application.ex         — OTP application, supervision tree
    mcp/
      server.ex            — Core MCP server logic
      server_manager.ex    — Manages child MCP server processes
      server_process.ex    — GenServer wrapping a child stdio process
      supervisor.ex        — Supervisor for MCP server processes
      config.ex            — Reads mcp_servers.json
      connection.ex        — Client connection state
      json_rpc_protocol.ex — JSON-RPC 2.0 parsing
      jsonrpc_client.ex    — Client for calling child servers
      flux_server.ex       — Flux-specific server config
      features/
        resources.ex       — Resource listing
        tools.ex           — Tool listing and dispatch
    events/
      broker.ex            — Pub/sub event broker
    cloud/
      durable_objects/
        client.ex          — Cloudflare Durable Objects HTTP client
    resources/
      message.ex, registry.ex, user.ex — Domain resources (Ash framework)
  mcpheonix_web/
    endpoint.ex            — Phoenix endpoint
    router.ex              — Routes: /mcp/stream (SSE), /mcp/rpc (JSON-RPC)
    controllers/
      mcp_controller.ex    — SSE stream and RPC handler
      page_controller.ex   — Default page
    plugs/
      mcp_rpc_plug.ex      — Parses JSON-RPC body
      raw_body_*.ex        — Raw body reading for RPC

Adding MCP Servers

Edit priv/config/mcp_servers.json:

{
  "mcpServers": {
    "your_server": {
      "command": "/path/to/executable",
      "args": ["arg1"],
      "env": { "API_KEY": "value" },
      "tools": {
        "tool_name": {
          "description": "What it does",
          "parameters": [
            { "name": "param1", "type": "string", "description": "..." }
          ]
        }
      }
    }
  }
}

Servers are started as child processes under OTP supervision and restarted on failure.

Setup

git clone https://github.com/jmanhype/MCPhoenix.git
cd MCPhoenix       # note: the repo name uses correct spelling
mix deps.get
mix phx.server     # starts on port 4001

Requirements

Dependency	Version
Elixir	>= 1.14
Erlang/OTP	>= 25
Phoenix	~> 1.7.0
Node.js	>= 18 (for child MCP servers)
Python	>= 3.9 (for Flux/Dart integration)

Optional Integrations

Integration	What's Needed
Flux image generation	Python 3.9+, Flux CLI, BFL_API_KEY
Dart task management	Node.js 18+, DART_TOKEN
Cloudflare Durable Objects	Worker deployment, CLOUDFLARE_WORKER_URL, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN

MCP Endpoints

Endpoint	Method	Purpose
/mcp/stream	GET	SSE stream; returns x-mcp-client-id header
/mcp/rpc	POST	JSON-RPC 2.0; pass x-mcp-client-id header

Key Dependencies

Package	Version	Purpose
phoenix	~> 1.7.0	Web framework
phoenix_live_view	~> 0.19.0	LiveView (included but not primary interface)
ash	~> 2.9	Resource framework
broadway	~> 1.0	Event processing
gen_stage	~> 1.2	Event streams
finch	~> 0.16	HTTP client
mint_web_socket	~> 1.0	WebSocket support
jason	~> 1.4	JSON encoding

Limitations

• The Cloudflare Durable Objects integration depends on a custom GitHub hex package (cloudflare_durable_ex) that may not be publicly available
• No authentication on the MCP endpoints
• SSE connections are not persisted across server restarts
• The Ash framework resources (User, Message, Registry) appear scaffolded but not fully integrated
• LiveView and LiveDashboard are included but not used for the MCP interface
• Log files (dev.log, phoenix_server.log) and temporary files are committed to the repo

License

MIT