tidewave_phoenix

# Tidewave Phoenix

Tidewave Phoenix is an MCP server that provides runtime-level tools for developing Phoenix apps using coding agents.

Your agent will be able to use this MCP server to talk to your running Phoenix app in development to:

- execute code in the context of the running app (like an IEx session for agents)
- read the app's live logs
- query your development database
- get source locations of modules and functions
- read documentation pinned to the exact hex package versions your project depends on

This MCP server is an open-source component of [Tidewave](https://tidewave.ai), the agentic development environment for Phoenix and Rails.

You can use this project as a standalone MCP server or integrated with the [Tidewave product](https://tidewave.ai) by following the installation instructions below.

## Installation

### 1. Add the Tidewave hex package to your app

#### Option 1: Manually

Add the `tidewave` package to your `mix.exs`:

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

Then, for Phoenix applications, go to your `lib/my_app_web/endpoint.ex` and right above the `if code_reloading? do` block, add:

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

   if code_reloading? do
```

> [!TIP]
> Tidewave works best with Phoenix LiveView v1.1 or later. Once you update it,
> make sure to enable the following options in your `config/dev.exs`:
>
> ```elixir
> config :phoenix_live_view,
>   debug_heex_annotations: true,
>   debug_attributes: true
> ```
>
> Those are enabled by default for Phoenix v1.8+ apps.

#### Option 2: Using Igniter

Alternatively, you can use `igniter` to automatically install Tidewave MCP into an existing Phoenix application:

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

# install tidewave
mix igniter.install tidewave
```

#### Umbrella projects

For umbrella projects, you can follow the manual steps above in the application that defines your Phoenix endpoint (typically `apps/your_app_web`).

### 2. Add the Tidewave MCP to your agent/editor

Add the Tidewave MCP server to your editor or MCP client configuration as the type "http" (streamable), pointing to the `/tidewave/mcp` path and port your web application is running at. For example, `http://localhost:4000/tidewave/mcp`.

We also have specific instructions for:

- [Claude Code](https://tidewave.hexdocs.pm/mcp_claude_code.html)
- [Codex](https://tidewave.hexdocs.pm/mcp_codex.html)
- [Cursor](https://tidewave.hexdocs.pm/mcp_cursor.html)
- [Neovim](https://tidewave.hexdocs.pm/mcp_neovim.html)
- [OpenCode](https://tidewave.hexdocs.pm/mcp_opencode.html)
- [VS Code](https://tidewave.hexdocs.pm/mcp_vscode.html)
- [Others](https://tidewave.hexdocs.pm/mcp.html)

> [!TIP]
> If you are using worktrees, you are likely running your web server
> on different ports, and therefore there isn't a single host and port
> combo you can use.
>
> In such cases, you may want to