From all-skills
Connects AI coding assistants to running Phoenix apps via MCP for runtime introspection: Ecto schemas, code execution, docs, logs, SQL queries. Prefer MCP tools over web fetches for version-pinned results.
How this skill is triggered — by the user, by Claude, or both
Slash command
/all-skills:tidewaveThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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.
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 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>.htmlsearch_package_docs instead of broader hex-doc searchesget_source_location instead of reading deps/<package>/lib/... with Readexecute_sql_query instead of shelling into psqlproject_eval instead of running iex -S mix snippetsWhy: 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.
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:
lib/).mix archive.install hex igniter_new
mix igniter.install tidewave
mix.exs:defp deps do
[
{:tidewave, "~> 0.5", only: :dev}
]
end
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
mix deps.get
Apply the manual steps to the application defining the Phoenix endpoint (typically apps/your_app_web).
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, plus a curl ping for raw verification and a troubleshooting table.
| Tool | Description |
|---|---|
project_eval | Execute Elixir code within the running application runtime |
execute_sql_query | Run SQL queries against the application database |
get_ecto_schemas | List all Ecto schema modules with their fields and associations |
get_ash_resources | List all Ash resources (when using the Ash framework) |
get_docs | Retrieve documentation for modules/functions using exact project versions |
search_package_docs | Query hexdocs.pm filtered to project dependencies (availability varies by framework) |
get_source_location | Find module/function source code file paths and line numbers |
get_models | List all application modules with their file locations |
get_logs | Access server logs; supports log level filtering (added v0.5.5) |
Note: search_package_docs may not be available in all frameworks. Verify availability for your setup.
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
if Mix.env() == :dev do
plug Tidewave,
allow_remote_access: false,
inspect_opts: [pretty: true, limit: 50]
end
| Option | Default | Description |
|---|---|---|
allow_remote_access | false | Allow connections from non-localhost |
inspect_opts | [] | Options passed to Kernel.inspect/2 for output formatting |
team | nil | Team configuration (e.g., [id: "my-company"]) |
extra_apps | [] | Additional OTP apps to include in source/module discovery (v0.5.6+) |
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.
http://localhost:9832cargo run -p tidewave-cli [-- --help]| Scenario | Use |
|---|---|
| Phoenix application | plug Tidewave in endpoint.ex |
| Container/remote dev | CLI app or plug with allow_remote_access: true |
| Non-Phoenix Elixir | CLI app |
| Standalone MCP server | CLI app on port 9832 |
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+.
Mix.env() == :dev or only: :dev in depsallow_remote_access: true only on trusted networksunsafe-eval in script-src directives and disables frame-ancestors restrictionsmix phx.serverhttp://127.0.0.1:4000/tidewave/mcp if IPv6 causes issuesplug Tidewave is placed before if code_reloading? in endpoint.exmix deps.getclaude in your terminal and confirm authenticationwhich claude:tidewave is added to the correct mix.exs in the umbrellanpx claudepluginhub vinnie357/claude-skills --plugin qaExposes MCP tools for Phoenix apps: execute Elixir code, run SQL queries, list Ecto schemas, fetch docs/logs/source. Use for AI assistant integration, runtime debugging, Tidewave setup.
Provides Tidewave MCP runtime tools for debugging, smoke testing, live state inspection, SQL queries, and Hex docs in running Phoenix apps. Use when evaluating code.
Guides Phoenix web app development including LiveView, contexts, channels, and production runtime configuration.