Tidewave Phoenix gives a coding agent an IEx into your running app

An MCP server that lives inside the development endpoint

The idea is narrower than most agent tooling and more useful for it. Tidewave Phoenix is described as an MCP server that provides runtime-level tools for developing Phoenix apps using coding agents, and it works by being mounted into the running application rather than by watching the source tree. The README lists what the agent gains: executing code in the context of the running app, like an IEx session for agents, reading the app's live logs, querying the development database, getting source locations of modules and functions, and reading documentation pinned to the exact hex package versions the project depends on. It is an open-source component of Tidewave, the agentic development environment for Phoenix and Rails, and it can be used standalone or with that product.

project_eval puts the runtime in the agent's hands

The headline tool is `project_eval`, which evaluates Elixir code within the running application and gives the agent access to the runtime, the dependencies and the in-memory data. The README compares it to an IEx for the agent. The stated use is grounding: instead of assuming behaviour, the agent can call a function to see what comes back, or reproduce a failing code path against live application state to debug it. That is a real difference in kind from a code search tool. A search tool tells you where something is written, while evaluation tells you what it does right now, with the same state the request would see. The trade-off is inherent to the feature and worth stating plainly, because the tool executes code in your development application under your application's own permissions.

The database, log and source lookup tools

Three smaller tools cover the routine questions an agent asks. `execute_sql_query` runs any SQL against the development database, and the README frames it as a way for the agent to verify the result of an action, which is the pattern where the agent changes data and then checks what landed. `get_logs` reads logs written by the server, with the example use case being reading the request log and a backtrace after something misbehaves. `get_source_location` returns the file and line for a given module or function, across both your app and its dependencies, so the agent can jump straight to a definition instead of grepping for it, including when the definition lives in a hex dependency rather than in your own tree.

get_docs resolves against the versions in mix.lock

The documentation tool is where this server differs from a generic docs lookup. `get_docs` returns the documentation for a module or function, and the README states that it consults the exact versions locked in your project's mix.lock. That detail matters more than it first appears. An agent that reads documentation for the current release of a package will be misled when your project pins an older version, and the mismatch shows up as code that compiles against one API and fails against another. Pinning the lookup to the lock file means the agent reads the same API surface your application was built against, which is the difference between advice that compiles and advice that does not.

Adding the tidewave package and the plug

The manual install is one dependency and one plug. Add the package to your `mix.exs`:

def deps do
  [
    {:tidewave, "~> 0.9", only: :dev},
    {:phoenix, ...},
  ]
end

The `only: :dev` part is the important detail, since the package never reaches a production dependency list. Then, in your `lib/my_app_web/endpoint.ex`, above the `if code_reloading? do` block, you add:

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

  if code_reloading? do

For umbrella projects the README says to follow those same manual steps in the application that defines your Phoenix endpoint, typically `apps/your_app_web`. It also notes that Tidewave works best with Phoenix LiveView v1.1 or later, and that with a newer LiveView you should enable `debug_heex_annotations: true` and `debug_attributes: true` in `config/dev.exs`, options that are on by default for Phoenix v1.8 and later apps.

Igniter install and pointing your editor at /tidewave/mcp

There is an automated route. The README offers `igniter` as an alternative that installs Tidewave MCP into an existing Phoenix application, using the archive and the installer:

# install igniter_new if you haven't already
mix archive.install hex igniter_new

# install tidewave
mix igniter.install tidewave

The second half of the setup is on the client side. You add the Tidewave MCP server to your editor or MCP client configuration with the type `http`, using the streamable transport, pointing at the `/tidewave/mcp` path on the port your web application runs at, for example `http://localhost:4000/tidewave/mcp`. The README lists dedicated instructions for Claude Code, Codex, Cursor, Neovim, OpenCode and VS Code, plus a general page for others. As with any MCP server, the agent decides when to call the tools, though the README notes you can also prompt it to call them explicitly.

Worktrees and the proxy that dispatches to the right port

Development setups often break the simple localhost assumption, and the README has a specific answer. If you are using worktrees, you are likely running your web server on different ports, so there is no single host and port combination you can point the client at. The suggested fix is to add `mix tidewave.proxy` as a STDIO MCP instead. The proxy adds a `port` parameter to all tool definitions and is responsible for dispatching to the correct application, which is what makes the setup workable when several copies of the app are running at once. A second edge case is multiple hosts and subdomains. For those you must use `*.localhost` domains, since browsers treat such domains as secure, and you need a matching session options block in your endpoint file for the application to run embedded across subdomains.

Localhost only, allowed origins and the CSP changes

The security posture is documented rather than assumed, and the defaults are conservative. The plug accepts options as `plug Tidewave, options`, and the first is `:allow_remote_access`, because by default Tidewave only allows requests from localhost even if the server listens on other interfaces, and the README links to security guidelines for when to relax that. The second is `:allowed_origins`, a list matched against the `Origin` header to prevent cross origin and DNS rebinding attacks, where each value is a string of the shape `[scheme:]//host[:port]` and the host may start with a wildcard, for example `["//localhost:8000", "//*.test"]`. There is also `:inspect_opts`. Two automatic changes are worth knowing about. If you have enabled a Content-Security-Policy, Tidewave enables `unsafe-eval` under `script-src` so contextual browser testing works, and it disables the `frame-ancestors` directive, both only in the environments where Tidewave is loaded, which is development by default.

Editorial conclusion

Adopt Tidewave Phoenix when your agents need to see the real behaviour of a running Phoenix application, since the MCP server exposes evaluation, logs, database queries and dependency documentation through one endpoint your editor can point at. Do not adopt it in an environment where the app is not in development, since the plug is loaded only under `Mix.env() == :dev` and the default configuration accepts requests from localhost only. Verify first that your editor's MCP client can talk to a streamable HTTP server at the `/tidewave/mcp` path, and read the `:allow_remote_access` and `:allowed_origins` options before enabling anything beyond localhost.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. tidewave-ai/tidewave_phoenix on GitHub