# Flute Webhooks MCP

Flute Webhooks MCP is an MCP (Model Context Protocol) server for Flute webhooks.
It lets an AI agent drive the `flute-webhooks` command-line tool through a standard protocol.
The server spawns a `flute-webhooks` process for each tool call and returns structured JSON.
It reports both successful results and the CLI error envelope back to the agent.

Credentials are never handled directly by this server.
Authentication lives in the OS keychain on the operator's machine, through `flute-webhooks auth login`.
The active profile is pinned at startup, so run one instance for each environment.

## Installing Flute Webhooks MCP

**Installing the Flute Webhooks CLI Prerequisite**

Flute Webhooks MCP requires the `flute-webhooks` CLI to be installed and authenticated first.

Install the latest version of `flute-webhooks`.
See: 
[Webhooks CLI](/docs/sdk/webhooks-cli) documentation.

Note the installed location of both binaries during this step.
A later configuration step may require their absolute paths.

Then authenticate, by running `flute-webhooks auth login`.

**Installing the Flute Webhooks CLI**

Download and install the application for your platform.
The latest installer can always be found at: [https://github.com/getflute/flute-webhooks-mcp/releases/latest](https://github.com/getflute/flute-webhooks-mcp/releases/latest)

**macOS / Linux (cURL)**

Use the following command to install the application for macOS or Linux using cURL.

```bash
curl -LsSf https://github.com/getflute/flute-webhooks-mcp/releases/latest/download/flute-webhooks-mcp-installer.sh | sh
```

**macOS / Linux (Homebrew)**

Use the following command to install the application for macOS or Linux using Homebrew.

```bash
brew install getflute/flute-webhooks-mcp/flute-webhooks-mcp
```

**Windows**

Use the following command from any location with either a Windows Command Prompt or a Windows PowerShell.
This does not require elevated permissions.

```bash
powershell -ExecutionPolicy Bypass -c "irm https://github.com/getflute/flute-webhooks-mcp/releases/download/v0.5.0/flute-webhooks-mcp-installer.ps1 | iex"
```

## Verifying the Webhooks CLI Installation

To verify that the installation was successful, run:

`flute-webhooks-mcp --help`

Help should display.

## Seeing Help for Webhooks CLI

To get a list of help commands, run:

`flute-webhooks-mcp --help`

Help should display.

## Updating Webhooks CLI

When launched, the application automatically checks for a newer version.
If a newer version exists, a non-blocking notice displays.

## Configuring Flute Webhooks MCP

Flute Webhooks MCP is configured entirely through environment variables and flags.
No configuration file is used by this server.

The following are the recognized environment variables.

| Variable | Default | Purpose |
|  --- | --- | --- |
| FLUTE_PROFILE | `sandbox` | Specifies the environment. Accepted values are `sandbox` or `production`, aliased as `prod`. This value is pinned at startup. |
| FLUTE_WEBHOOKS_BIN | unset | Specifies the absolute path to the `flute-webhooks` binary. This value should always be set explicitly. |
| FLUTE_MCP_TIMEOUT_SECS | `30` | Sets the timeout, in seconds, for each spawned `flute-webhooks` process. |
| FLUTE_MCP_DEBUG | unset | Set to any non-empty value to route `flute-webhooks` standard error output into this server's tracing. Unset the variable to turn this off. |
| RUST_LOG | `info` | Sets the tracing filter used by this server. Log output is written only to standard error. |


### Locating the Binaries

Assume neither binary is on the host application's search path.
Configure both `command` and `FLUTE_WEBHOOKS_BIN` using absolute paths.

A host application spawns `flute-webhooks-mcp` directly, without first loading a login shell.
An application launched from a desktop icon or an IDE often inherits a minimal search path.
That a command works when typed into a terminal proves nothing about the host application's own path.

Two separate lookups depend on this, and each fails in a different way.
The `command` setting is the path the host application uses to launch this server.
If that path cannot be resolved, the server never starts, and no log file is produced.
The `FLUTE_WEBHOOKS_BIN` setting is where this server finds the `flute-webhooks` CLI.
Left unset, this falls back to a search path lookup that usually fails under a host application.
When that lookup fails, the server prints an error to standard error and exits with status two.

Find the real paths using your own shell.

```bash
# macOS / Linux
command -v flute-webhooks
command -v flute-webhooks-mcp
```

In a Windows PowerShell from any location, run:

```powershell
# Windows (PowerShell)
(Get-Command flute-webhooks).Source
(Get-Command flute-webhooks-mcp).Source
```

If either command returns nothing, that binary is not installed for the current user.
The binary must be installed first.

For reference, the installers place `flute-webhooks-mcp` in the following locations.

| Installed Through | Location |
|  --- | --- |
| Shell installer, PowerShell installer, or `cargo install` | `~/.cargo/bin`, or `%USERPROFILE%\.cargo\bin` on Windows. |
| Homebrew, on Apple Silicon macOS | `/opt/homebrew/bin` |
| Linuxbrew, on 64-bit Linux | `/home/linuxbrew/.linuxbrew/bin` |


The `FLUTE_WEBHOOKS_BIN` variable must name the executable file itself, not its containing folder.
A missing path, or a folder given in its place, causes the server to exit at startup.

Neither configuration format expands a home directory shortcut, so write each path out in full.
On Windows, escape backslashes in a JSON value, or use a literal string in a TOML value.
Include the `.exe` file extension on a Windows path.

### Configuring a Host Application

Most host applications read MCP server settings from their own configuration file.
Replace every placeholder path below with the absolute paths found earlier.

```json
{
  "mcpServers": {
    "flute-webhooks-sandbox": {
      "command": "/path/to/mcp/flute-webhooks-mcp",
      "env": {
        "FLUTE_PROFILE": "sandbox",
        "FLUTE_WEBHOOKS_BIN": "/path/to/cli/flute-webhooks"
      }
    },
    "flute-webhooks-prod": {
      "command": "/path/to/mcp/flute-webhooks-mcp",
      "env": {
        "FLUTE_PROFILE": "production",
        "FLUTE_WEBHOOKS_BIN": "/path/to/cli/flute-webhooks"
      }
    }
  }
}
```

If a server shows as failed, check the host application's MCP logs for this server's error output.
A missing binary message in that log means `FLUTE_WEBHOOKS_BIN` is unset or incorrect.
No log file at all usually means the `command` path itself did not resolve.

Codex stores its MCP server settings in `~/.codex/config.toml`.
The Codex app, the Codex CLI, and the Codex IDE extension all share this file.

```toml
[mcp_servers.flute-webhooks-sandbox]
command = "/path/to/mcp/flute-webhooks-mcp"
env = { FLUTE_PROFILE = "sandbox", FLUTE_WEBHOOKS_BIN = "/path/to/cli/flute-webhooks" }

[mcp_servers.flute-webhooks-prod]
command = "/path/to/mcp/flute-webhooks-mcp"
env = { FLUTE_PROFILE = "production", FLUTE_WEBHOOKS_BIN = "/path/to/cli/flute-webhooks" }
```

## Available Tools

Flute Webhooks MCP exposes eleven tools.
Every tool result is the upstream CLI's own JSON output, passed through unchanged.
The shape an agent sees comes directly from `flute-webhooks`, not from this server.

The following tools are available, along with whether each is safe to repeat (idempotency).

| Tool | Idempotent |
|  --- | --- |
| endpoints_list | Yes. |
| endpoints_get | Yes. |
| endpoints_create | No. A repeated call creates a second endpoint. |
| endpoints_update | Yes. This call is a merge patch, so omitted fields stay unchanged. |
| endpoints_delete | Yes. A second call returns a not found status. |
| endpoints_ping | Yes. |
| event_types_list | Yes. |
| deliveries_list | Yes. |
| deliveries_get | Yes. |
| deliveries_retry | No. Each call schedules another retry attempt. |
| auth_status | Yes. |


A small number of upstream commands are intentionally excluded from this server.

* The interactive `tui` and `auth login` because both need a live terminal.
* The `listen` command because it runs continuously and does not produce a single JSON result.
* The `update` command because it is an operator-only action.


### Checking the Upstream CLI Version

This server requires `flute-webhooks` version `0.7.1` or newer.
It has been developed and tested against version `0.7.4`.
Older CLI versions are not supported, since this server tracks the current upstream contract.

Two upstream changes set this minimum version.

| Needed For | Landed In | What This Server Relies On |
|  --- | --- | --- |
| Every tool result shape | `v0.7.0` | The Flute v2 specification pass, including list envelopes, a merge patch on endpoint update, and a full delivery log returned by retry. |
| The `auth_status` tool | `v0.7.1` | The `auth keys` subcommand, which replaced an older subcommand named `auth token`. |


To check the installed version, run:

* `flute-webhooks --version`


## Handling Errors

A tool result should be checked using the MCP `isError` flag, never by inspecting its shape.
An error result contains a structured `kind` field, at minimum.
The following are the possible values of the `kind` field.

| Kind | Meaning |
|  --- | --- |
| api | The Flute API returned an error response, along with a status code. |
| transport | A network or connection problem prevented the request from completing. |
| auth | Credentials are missing or invalid. Run `flute-webhooks auth login` on the operator's machine. |
| decode | The CLI produced output that this server could not parse. |
| client | The request was rejected by this server before the CLI ran. |
| spawn | The `flute-webhooks` process could not be started. |
| timeout | The `flute-webhooks` process did not finish within the configured timeout. |
| bad_output | The CLI produced output that was not valid JSON. |


An `api` error also includes a `status` field, and a `correlation_id` field when one is available.
Errors with a `kind` of `transport`, or an `api` status between 500 and 504, are safe to retry.

A startup failure never reaches this layer.
A missing or invalid `flute-webhooks` path causes the process to exit with status two immediately.
The host application sees this as a server that will not start, rather than as a tool error.

## License

MIT.