MCPheonix

@jmanhype

About MCPheonix

A simplified implementation of the Model Context Protocol (MCP) server using Elixir's Phoenix Framework.

#mcpheonix #model-context-protocol #elixir #phoenix-framework

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "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": "..."
            }
          ]
        }
      }
    }
  }
}

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is MCPheonix?

MCPheonix is an MCP server built on the Phoenix Framework (Elixir) that exposes Server-Sent Events and JSON-RPC endpoints for MCP clients. It manages multiple child MCP servers as supervised OTP processes, configured via a JSON file. This server is intended for developers who need to orchestrate specialized MCP sub-servers (e.g., Flux image generation, Dart task management) from a single Phoenix web server.

How to use MCPheonix?

Clone the repository, run mix deps.get, then mix phx.server to start the server on port 4001. Child MCP servers are defined in priv/config/mcp_servers.json and are automatically started at boot. Clients connect to GET /mcp/stream for SSE and POST /mcp/rpc for JSON-RPC 2.0 requests.

Key features of MCPheonix

Runs a Phoenix web server on port 4001 with SSE and JSON-RPC endpoints.
Manages child MCP servers as supervised OTP processes.
Supports Flux image generation and Dart task management as built-in child servers.
Accepts JSON configuration for adding arbitrary child MCP servers.
Event system powered by Broadway and GenStage.
Optional Cloudflare Durable Objects integration (experimental).

Use cases of MCPheonix

Centralized MCP server routing tool calls to multiple specialized child servers.
Managing Flux image generation as a subprocess via MCP.
Managing Dart task management as a subprocess via MCP.
Building custom MCP server orchestration with Elixir OTP supervision.

FAQ from MCPheonix

What runtime dependencies does MCPheonix require?

Elixir >= 1.14, Erlang/OTP >= 25, Phoenix ~> 1.7, Node.js >= 18, and Python >= 3.9 (optional for Flux/Dart).

How do I add a new child MCP server?

Edit priv/config/mcp_servers.json with the server's command, arguments, environment variables, and tool definitions. The server starts automatically as a supervised process.

What MCP endpoints are available?

GET /mcp/stream – SSE stream (returns x-mcp-client-id header).
POST /mcp/rpc – JSON-RPC 2.0 (requires x-mcp-client-id header).

Does MCPheonix support authentication?

No. The MCP endpoints currently have no authentication built-in.

What are the known limitations?

No authentication, SSE connections are not persisted across restarts, and the Cloudflare Durable Objects integration relies on a custom hex package that may not be publicly available.

Frequently asked questions