MCPheonix
About
A simplified implementation of the Model Context Protocol (MCP) server using Elixir's Phoenix Framework.
Details
- Author
- jmanhype
- GitHub stars
- 67
- Downloads
- 329
- Categories
- Other
Jump to
- 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).
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
MCPheonixCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
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.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"mcpheonix": {
"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": "..."
}
]
}
}
}
}
}
}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": "..."
}
]
}
}
}
}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
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
