Phantom.Plug (phantom v0.1.0)

View Source

Main Plug implementation for MCP HTTP transport with SSE support.

This module provides a complete MCP server implementation with:

  • JSON-RPC 2.0 message handling
  • Server-Sent Events (SSE) streaming
  • CORS handling and security features
  • Session management integration
  • Origin validation

In your Phoenix router where you can accept JSON:

  pipeline :mcp do
    plug :accepts, ["json"]
  end

  scope "/mcp" do
    pipe_through :mcp

    forward "/", Phantom.Plug,
      router: Test.MCPRouter,
      validate_origin: false
  end

For in your Plug Router after you parse the body:

  use Plug.Router
  plug :match
  plug Plug.Parsers,
    parsers: [{:json, length: 1_000_000}],
    pass: ["application/json"],
    json_decoder: JSON
  plug :dispatch

  forward "/mcp",
    to: Phantom.Plug,
    init_opts: [validate_origin: false, router: Test.MCPRouter]

Here are the defaults:

[
  origins: ["http://localhost:4000"],
  validate_origin: true,
  session_timeout: 30000,
  max_request_size: 1048576
]

Telemetry

Telemetry is provided with these events:

  • [:phantom, :plug, :request, :connect] with meta: ~w[session_id last_event_id router opts conn]a
  • [:phantom, :plug, :request, :disconnect] with meta: ~w[session router conn]a
  • [:phantom, :plug, :request, :exception] with meta: ~w[session router conn stacktrace request exception]a

Summary

Functions

Callback implementation for Plug.call/2.

Initializes the plug with the given options.

Types

opts()

@type opts() :: [
  router: module(),
  origins: [String.t()] | :all | mfa(),
  validate_origin: boolean(),
  session_timeout: pos_integer(),
  max_request_size: pos_integer()
]

Functions

call(conn, opts)

Callback implementation for Plug.call/2.

init(opts)

Initializes the plug with the given options.

Options

  • :router - The MCP router module (required)
  • :origins - List of allowed origins or :all (default: localhost)
  • :validate_origin - Whether to validate Origin header (default: true)
  • :session_timeout - Session timeout in milliseconds (default: 300_000)
  • :max_request_size - Maximum request size in bytes (default: 1MB)