phxagents.dev
Star 517 Install

Tidewave MCP for Phoenix

Tidewave MCP gives your AI editor runtime intelligence for a running Phoenix app — live SQL, code evaluation, Ecto schema introspection, and version-exact hex docs over the Model Context Protocol. phxagents ships a dedicated Tidewave integration skill in every v3 edition, so the agent can prefer runtime evidence over shell-based guesses when its client exposes the connection.

What is Tidewave MCP?

Tidewave (from Dashbit, the team behind Elixir and Livebook) exposes a running Phoenix application’s runtime to AI editors and coding agents through an MCP server. Instead of reading static files and guessing, the agent can query the live database, evaluate code in the running app, look up Ecto schemas and source locations, read logs, and fetch documentation pinned to your mix.lock versions.

Claude Code receives the full Tidewave-aware plugin; Amp, Codex, Pi and OpenCode receive the same tidewave-integration skill in their generated editions. Installing any edition exposes no fixed-port server and registers no MCP endpoint. When a client makes Tidewave tools available in a dev session, the skill can use them; adapted workflows keep a complete local fallback when it cannot.

Runtime tools phxagents uses

The names below are how Claude Code exposes the tools. Other MCP clients may label them differently, but the capabilities and local fallbacks are the same:

TaskClaude Code tool nameFallback
Version-exact hex docsmcp__tidewave__get_docsweb_fetch hexdocs.pm/…
Evaluate code in the appmcp__tidewave__project_evalmix run -e "…"
Run a SQL querymcp__tidewave__execute_sql_querypsql $DATABASE_URL
Find a source locationmcp__tidewave__get_source_locationgrep -rn "defmodule"
List Ecto schemasmcp__tidewave__get_ecto_schemasRead lib/*/schemas/
Read runtime logsmcp__tidewave__get_logstail -f log/dev.log

Setup & detection

Add Tidewave to your Phoenix app (see tidewave.ai), then confirm the MCP endpoint is reachable in development:

Check the Tidewave MCP endpoint 
curl -s http://localhost:4000/tidewave/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

Exposing that HTTP server and registering it with an MCP client are separate steps. phxagents never silently registers a fixed port. Replace $PORT below with the port used by the current Phoenix project.

Claude Code

Register and verify 
claude mcp add --transport http tidewave \
  http://localhost:$PORT/tidewave/mcp

# Then run /mcp inside Claude Code

Codex

Register and inspect 
codex mcp add tidewave --url http://localhost:$PORT/tidewave/mcp
codex mcp list

Start Codex and use /mcp to verify the tools are connected; codex mcp list confirms configuration only.

OpenCode

Add the endpoint to the project’s opencode.json or the global ~/.config/opencode/opencode.json:

opencode.json 
{
  "mcp": {
    "tidewave": {
      "type": "remote",
      "url": "http://localhost:$PORT/tidewave/mcp",
      "enabled": true
    }
  }
}

Amp and Pi: the generated package does not configure Tidewave. Treat MCP as an external runtime capability and follow your client’s current setup. The skills remain usable without it. See the runtime capability matrix for the support boundary.

Dev only — never in production

Tidewave tools evaluate code and run SQL against the live runtime, so phxagents enforces a hard rule: Tidewave is dev-only. The plugin never uses these tools in production contexts and avoids shared dev servers that hold copies of production data. SQL is treated as read-heavy — execute_sql_query for SELECTs, with care around mutations.

Learn more