---
title: "Aider MCP Setup with ToolPiper"
description: "Connect Aider's AI pair-programming CLI to ToolPiper's local MCP server. Over 300 local tools available alongside Aider's repo-aware coding workflow."
date: 2026-05-17
author: "Ben Racicot"
tags: ["Aider", "MCP", "Model Context Protocol", "Setup Guide", "Privacy", "macOS", "CLI"]
type: "article"
canonical: "https://modelpiper.com/blog/aider-mcp-setup/"
---

# Aider MCP Setup with ToolPiper

> Connect Aider's AI pair-programming CLI to ToolPiper's local MCP server. Over 300 local tools available alongside Aider's repo-aware coding workflow.

## TL;DR

Aider's MCP support landed in late 2025. Register ToolPiper through Aider's config file (~/.aider.conf.yml) or with a --mcp-server flag at startup. ToolPiper's over 300 tools become callable from inside an Aider session.

Aider is the CLI-first AI pair programmer. It works from a git repo and makes commits as it edits, which suits a tight feedback loop. MCP support arrived in late 2025 and opens the door to tool calls beyond the built-in file-edit and shell-execute primitives. ToolPiper plugs in through the same MCP path any other server uses.

## How do I configure Aider to use ToolPiper?

Edit Aider's config file `~/.aider.conf.yml` and add an `mcp-servers` entry for ToolPiper. Alternatively, pass `--mcp-server name=toolpiper,url=http://127.0.0.1:9998/mcp` on the command line. Restart Aider for the change to take effect.

Config file path (YAML):

```
mcp-servers:
  - name: toolpiper
    transport: http
    url: http://127.0.0.1:9998/mcp
```

Command-line path:

```
aider --mcp-server name=toolpiper,transport=http,url=http://127.0.0.1:9998/mcp
```

The config file approach is better for repeated use. Save it once and every Aider invocation picks up ToolPiper automatically. The CLI flag is useful for one-off sessions or testing.

## Does Aider support HTTP MCP, or only stdio?

Both as of the late-2025 release. Earlier Aider versions only supported stdio MCP servers, which would require a stdio bridge for ToolPiper. Check your version with `aider --version`. If it's older than 0.69 or so, update before continuing.

HTTP is the recommended transport. ToolPiper is already a running app, so pointing Aider at its HTTP endpoint avoids the stdio bridge and the process-spawning that comes with it.

If you need stdio (older Aider, or strict environment policies that block HTTP), the stdio fallback uses a small `toolpiper-mcp-stdio` binary that bridges stdin/stdout to ToolPiper's HTTP API. It ships with ToolPiper. The config entry shape changes to:

```
mcp-servers:
  - name: toolpiper
    transport: stdio
    command: /Applications/ToolPiper.app/Contents/MacOS/toolpiper-mcp-stdio
```

## How does Aider's model call ToolPiper tools?

Aider hands the MCP tool catalog to the model along with Aider's built-in file-edit tools. The model decides when to call an MCP tool based on the prompt. Tool calls show up in Aider's output as you watch.

Concrete pattern: ask Aider to fix a UI bug, including _"take a screenshot first to see the current state"_. The model calls `vision_screenshot` through ToolPiper, gets the image, identifies the issue, then makes the code edits using Aider's normal flow. End to end in one prompt.

For mostly-code tasks, Aider's built-in file edit primitives are faster than MCP roundtrips. ToolPiper's tools shine when the task crosses the code/system boundary: capturing screen state, running browser tests, transcribing audio, querying OAuth-backed services.

## How do I verify the connection?

Start Aider with `--verbose` and watch for MCP tool registration in the startup output. Aider should log discovered ToolPiper tools as it connects to the server.

Sample verbose output:

```
$ aider --verbose
...
Connecting to MCP server: toolpiper at http://127.0.0.1:9998/mcp
Discovered over 300 tools from toolpiper
Ready.
```

End-to-end test: in the Aider session, prompt _"take a screenshot of my screen and describe what's open"_. If the model invokes a ToolPiper tool and reports back, the wiring is correct.

## What if Aider can't see ToolPiper?

Four checks. Aider version supports MCP. ToolPiper is running. Config syntax is valid YAML. Endpoint actually responds. Each rules out a different failure mode.

1.  Aider version. `aider --version`. Pre-0.69 builds don't reliably support MCP. Update with `pip install --upgrade aider-chat`.
2.  ToolPiper running. `curl http://127.0.0.1:9998/health` returns JSON. Connection refused means ToolPiper isn't open.
3.  YAML valid. Run `python3 -c "import yaml; yaml.safe_load(open('~/.aider.conf.yml'.replace('~', '/Users/$(whoami)')))"` or a similar YAML validator. Indentation errors are a common YAML failure mode.
4.  Endpoint reachable. `curl http://127.0.0.1:9998/mcp`. A 404 or connection refused means ToolPiper isn't serving MCP at that path.

For full MCP setup options across other editors, see [MCP Setup on Mac](/blog/mcp-setup-guide-mac).

## FAQ

### Where is Aider's config file?

The default is `~/.aider.conf.yml`. Aider also reads `.aider.conf.yml` in the current working directory if one exists there. The local config takes precedence.

### Does Aider need to be restarted for config changes?

Yes. Aider reads its config and registers MCP servers at startup. Changes to `~/.aider.conf.yml` take effect on the next `aider` invocation.

### Can Aider use multiple MCP servers?

Yes. `mcp-servers` is a YAML list. Add multiple entries, each with its own name and URL. Aider exposes the combined tool catalog to the model.

### Does Aider record MCP tool calls in its git commits?

Aider commits code changes it makes. Pure tool-call side effects (like a screenshot) aren't committed because they don't touch files in the repo. If a tool call writes a file to your repo, that file is included in the next commit.

### What happens when ToolPiper is unreachable during an Aider session?

Aider falls back to its built-in tools and surfaces a warning. The session continues, but ToolPiper-specific capabilities are unavailable until ToolPiper comes back. Aider doesn't fail the entire session over a single MCP server going dark.