tidewave

Tidewave MCP Dev Tools

Tidewave is a dev tool by Dashbit that connects AI coding assistants to running Phoenix applications via the Model Context Protocol (MCP). It exposes runtime introspection tools: Ecto schemas, code execution, documentation lookup, log inspection, and SQL queries.

Current version: ~> 0.5 (v0.5.6 released 2026-03-13 — adds :extra_apps plug option)

When connected, prefer MCP tools over web fetches

When Tidewave MCP is connected to an Elixir/Phoenix project, route documentation, source, and runtime queries through the MCP tools — not WebFetch or hexdocs.pm.

• get_docs instead of WebFetch on hexdocs.pm/<package>/<Module>.html
• search_package_docs instead of broader hex-doc searches
• get_source_location instead of reading deps/<package>/lib/... with Read
• execute_sql_query instead of shelling into psql
• project_eval instead of running iex -S mix snippets

Why: MCP tool calls return results pinned to the exact versions in the project's mix.lock, complete in a single round-trip, and skip HTML→markdown conversion and page chrome — significantly fewer tokens per lookup than WebFetch, and the answer is guaranteed to match the running app rather than whatever version is on hexdocs.pm today.

Using tidewave in tier prompts

When a worker in a staged pipeline interacts with unfamiliar dependencies, the lead's prompt to that worker MUST explicitly direct the worker to verify dep APIs via tidewave MCP tools before stubbing or implementing.

Add this block to Tier 2 (test author) and Tier 3 (implementer) prompts when the work touches a dep not already exercised in the codebase:

## Module docs via tidewave (PREFERRED over WebFetch or guessing)

For unfamiliar deps, verify the actual API surface via tidewave MCP before stubbing or implementing:

- `mcp__tidewave-<app>__search_package_docs` (q: "<ModuleName>") — keyword search across installed package docs
- `mcp__tidewave-<app>__get_docs` (module: "<Module>", function: "<func>") — full docstrings for a specific function

Particularly important for: <list the specific deps this tier touches>.

Tidewave hits the running BEAM's loaded modules — it returns what is ACTUALLY in the dep, not what the model remembers from training data. Guessing produces code that does not compile or behaves wrong; tidewave produces code matching the real API surface.

The lead lists the SPECIFIC dep names in the prompt — abstract "use tidewave" instructions are ignored. Naming the dep (Cloak, Slipstream, Phoenix.Token, Mox, etc.) and the exact MCP tool names triggers the worker to call them.

This applies whenever a tier worker touches a dependency that:

• Is new to the codebase (not already imported / used in lib/).
• Has changed API across a recent major version.
• The worker would otherwise stub from training-data memory.

Installation

New Projects (via Igniter)

mix archive.install hex igniter_new
mix igniter.install tidewave

Existing Projects (Manual)

1. Add to mix.exs:

defp deps do
  [
    {:tidewave, "~> 0.5", only: :dev}
  ]
end

2. Add plug to lib/my_app_web/endpoint.ex before the code_reloading? block:

if Mix.env() == :dev do
  plug Tidewave
end

if code_reloading? do
  # ...existing code reload plugs...
end

3. Fetch dependencies:

mix deps.get

Umbrella Projects

Apply the manual steps to the application defining the Phoenix endpoint (typically apps/your_app_web).

MCP Server Configuration

Tidewave exposes an MCP server at /tidewave/mcp on the Phoenix app's port. The transport type is HTTP (streamable) — SSE was removed in v0.4.0. Tidewave is unauthenticated; decline any "Authenticate" prompt the editor offers.

Default URL: http://localhost:4000/tidewave/mcp

See references/mcp-setup.md for verbatim setup commands and JSON config for Claude Code, Codex CLI, Gemini CLI, and opencode, an unverified Cursor/VS Code/Zed config table, plus a curl ping for raw verification and a troubleshooting table.

MCP Tools Reference

Note: search_package_docs may not be available in all frameworks. Verify availability for your setup.

Usage Patterns

See "When connected, prefer MCP tools over web fetches" at the top of this skill for the routing rule.

Introspect schemas before writing queries:

get_ecto_schemas → discover schema structure → execute_sql_query

Look up documentation for project dependencies:

get_docs for specific modules, search_package_docs for broader hex dependency searches

Execute and test code in the running app:

project_eval → run Elixir expressions against live application state

Plug Configuration Options

if Mix.env() == :dev do
  plug Tidewave,
    allow_remote_access: false,
    inspect_opts: [pretty: true, limit: 50]
end

CLI App (Standalone MCP Server)

The Tidewave desktop/CLI app (tidewave_app) runs a standalone MCP server without requiring a Phoenix application. Useful for containers, remote dev environments, or non-Phoenix Elixir projects.

• Default server: http://localhost:9832
• Only allows access from the same machine by default

Installation

• Desktop app (macOS, Windows, Linux): https://tidewave.ai/install
• Development CLI: cargo run -p tidewave-cli [-- --help]

When to Use CLI vs Phoenix Plug

LiveView Debug Annotations

Enable in config/dev.exs to help Tidewave map rendered HTML back to source HEEx templates:

config :phoenix_live_view,
  debug_heex_annotations: true

config :phoenix,
  debug_attributes: true

Requires Phoenix LiveView v1.1+.

Security

• Dev-only: Always guard with Mix.env() == :dev or only: :dev in deps
• Localhost-only: Tidewave only accepts localhost requests by default
• No production use: Tidewave exposes code execution and database access — never deploy to production
• Docker/remote dev: Set allow_remote_access: true only on trusted networks
• CSP: Tidewave injects unsafe-eval in script-src directives and disables frame-ancestors restrictions

Troubleshooting

MCP connection fails

• Verify Phoenix server is running: mix phx.server
• Check the port matches your configuration (default 4000)
• Try http://127.0.0.1:4000/tidewave/mcp if IPv6 causes issues

Tools not appearing

• Confirm plug Tidewave is placed before if code_reloading? in endpoint.ex
• Restart the Phoenix server after adding the plug
• Verify the dependency is installed: mix deps.get

Claude Code authentication error

• Run claude in your terminal and confirm authentication
• Verify CLI availability: which claude

Umbrella project issues

• Add the plug only in the endpoint of the web application
• Ensure :tidewave is added to the correct mix.exs in the umbrella