Blog

Upgrade Your Pi Agent with Subagents + MCP

Alexander Galea

Alexander Galea

Upgrade Your Pi Agent with Subagents + MCP

TLDR — I’ll show you how to install subagents and MCP for the Pi agent harness. pi-subagents gives Pi Claude Code-style parallel delegation, and I’ll demo how to use it to explore a repo. pi-mcp-adapter gives Pi MCP, and I’ll demo how authentication works by connecting to a remote MCP server.

Pi is a lightweight coding agent harness. It wraps an LLM, gives it read, write, edit and bash, and stops there. That’s the whole design.

Two things I need every day are not in that list: subagents and MCP. They’re not exactly missing, they just don’t ship with the base install. Pi is easy to extend, and other people have already done the work, so this post is two pi install commands and a demo for each.

If you’d rather watch me do this tutorial, it’s all in the video above — watch it on YouTube. Otherwise keep reading, everything’s below.

Install and launch Pi

Watch Video

If you haven’t installed Pi yet, grab the command from pi.dev and paste it into your terminal:

curl -fsSL https://pi.dev/install.sh | sh

Press y when it asks, then run pi to spin it up.

The startup panel will show:

  • Context — the files loaded into Pi.
  • Agent skills — every skill detected on your system.
  • Themes — I have Dracula set.

If you’ve never installed a Pi extension, then you won’t see that section yet.

Subagents

Watch Video

Install pi-subagents

Let’s install tintinweb/pi-subagents. It’s sitting at about a thousand stars on GitHub.

There are other options for subagents in Pi, and I picked this one because it does Claude Code-style subagents. That’s what I’m used to, and I wanted the same experience inside Pi.

pi install npm:@tintinweb/pi-subagents

Run that outside of Pi, then start pi again. The startup panel now has an Extensions section with tintinweb/pi-subagents in it. If you don’t see it, the extension didn’t install correctly.

Explore a repo with ten subagents

I’m working in the ZazenCodes Season 3 repo, which has all of the demos from my videos this year. Let’s explore the src folder.

If you want to run this demo yourself, clone it and start Pi in there:

git clone https://github.com/zazencodes/zazencodes-season-3.git
cd zazencodes-season-3
pi

First attempt:

Explore my source folder in the current working directory using subagents.

That launched a single Explore subagent. Not exactly what I wanted, so I stopped it and asked this instead:

Use subagents to explore what's in the source folder inside of this repository.
Use 10 different subagents to do this in parallel and then bring their results
back together.

Pi ran a few bash commands to size up the folder, then triggered ten parallel subagents to inspect src.

The UI here is the reason I picked this plugin. You get a workflow row with 0/10 agents and a running clock, and pressing enter drops you into the phases view where checkmarks land as agents finish. Arrow right and you’re looking at the individual subagents. I opened the one still running and could see its model (Claude Haiku, through OpenCode), the exact prompt it was given, and an empty outcome field that filled in a few seconds later.

The Pi subagent workflow shows nine of ten explorers complete and the selected agent's prompt and outcome
The Pi subagent workflow shows nine of ten explorers complete and the selected agent's prompt and outcome

When they all finished, their results got pulled back into the main context and the main agent carried on with the summary.

Here’s the part that matters. The workflow summary said about 300,000 tokens, a minute and a half, and around 300 tool uses, mostly list calls. Then I looked at my main context: 24,000 tokens, roughly 10% of the window. That 300k is what the isolation saved me. All the nitty-gritty crawling happened somewhere else, and my main agent got the answer with a clean context and room to keep going.

I wouldn’t use Pi without this. It’d feel very incomplete.

Configure the subagent model

Watch Video

My main model was GPT 5.6 Terra, so why were the subagents running Claude Haiku? Because the Explore agent type defaults to Haiku and only falls back to inherit. That surprised me. I assumed it would inherit the parent model.

The extension adds an /agents command for managing this. Type it in Pi and walk the menu:

  1. Agent types — the list of subagent roles, with their models beside them. Explore shows Haiku 4.5.
  2. Select Explore, then eject.
  3. Choose personal rather than project, so the override applies everywhere on your machine.

Pi prints the path it ejected to. Open that file in another pane and the override is right there:

Pi's Agent types menu and the ejected Explore agent configuration file
Pi's Agent types menu and the ejected Explore agent configuration file

model: anthropic/claude-haiku-4.5

Swap it:

model: openai/gpt-5.6-luna

You can restart Pi and run it again in order to confirm it’s working. It should report the subagent model as openai-codex/gpt-5.6-luna now. This is a well-known pattern for subagents: using a cheap model for exploration and a more expensive model as the main driver to pull results back to.

MCP

Watch Video

Install pi-mcp-adapter

Now let’s install MCP for Pi. The extension is pi-mcp-adapter, and it’s also sitting at about a thousand stars. There are other adapters available for Pi MCP. This one was just my pick.

pi install npm:pi-mcp-adapter

Again, run that outside Pi and start it back up. Both extensions are now listed. Typing /mcp gives you a set of commands that didn’t exist before, and the one you want first is the setup guide:

  1. Type /mcp and pick the top entry to open the MCP setup guide.
  2. It asks where the config should live. Choose add to this project.
  3. Scroll down and choose scaffold project .mcp.json.

Pi's MCP setup guide with the project and global configuration choices
Pi's MCP setup guide with the project and global configuration choices

Pi writes a starter file to your working directory. Exit, then cat .mcp.json and you’ll see it’s empty:

{
  "mcpServers": {}
}

Now put a server in it. For the demo I connected Floot, an AI connector that handles a backend, a Postgres database and hosting. Sign up (it’s free and takes a second), then find their Add to Cursor and others option, which gives you a streamable HTTP connector and a URL. I copied those instructions and pasted them straight into Pi:

Install this MCP server inside of this project.
<paste Floot's connector instructions here>

Pi made the edit itself, and .mcp.json came out like this:

{
  "mcpServers": {
    "floot": {
      "url": "https://mcp.floot.com/mcp"
    }
  }
}

You can just as easily write that by hand. Either way, start a new Pi session afterwards so it reads the config, and the status bar picks up MCP · 1 server enabled.

Build an app through an MCP server

Watch Video

Now we can actually test out Pi with our MCP server. If you’re following along
with me then you can trigger Floot by running a prompt like this:

Build me a working feedback hub with Floot. Create a form that saves responses
to a database, and a way to browse them. Make it fun by having a little
pixelated character on the screen that reacts when stuff happens.

Then I did the MCP OAuth flow. For me it went down like this:

  1. Pi stops and says server floot requires OAuth authentication.
  2. Press Ctrl+O to expand that message. It contains a URL.
  3. Open the URL in your browser and approve the connection.
  4. Approving opens a new browser tab on localhost:50604. That tab holds your authorization token — this is the step that’s easy to miss, because the dialog on the first tab looks like the end of the flow.
  5. Copy the token, paste it back into Pi.

Pi's expanded OAuth prompt with the authorization URL and callback instructions
Pi's expanded OAuth prompt with the authorization URL and callback instructions

I expect that the flow would be a bit smoother in Codex or Claude. With Pi it takes a bit more engineering (which, of course, I love).

Once authenticated, the tool calls start streaming: floot_get_guides to read the docs, floot_list_files to look around the workspace, then floot_edit_file and floot_apply_patch to write the app.

Pi streaming Floot MCP tool calls while the generated feedback hub opens beside it
Pi streaming Floot MCP tool calls while the generated feedback hub opens beside it

Add your own MCP server globally

Watch Video

Next we can set up global MCP tools with Pi.

Typing /mcp on its own now lists servers rather than showing the setup screen, so to get back to the config menu you run mcp setup. This time pick the global option, and Pi tells you which file to edit.

To show a second one I used my own random number MCP server. It runs locally through uv instead of over HTTP, so the entry looks different from Floot’s:

{
  "mcpServers": {
    "random-number": {
      "command": "uvx",
      "args": ["random-number-mcp"]
    }
  }
}

Clone the repo first and point --directory at wherever it landed. I had to use the absolute path to get it running.

Then type reload in Pi to pick up the new config, and the status bar should read MCP · 2 servers enabled: Floot from the project .mcp.json, random number from the global one.

Project and global MCP configuration files open side by side in Pi
Project and global MCP configuration files open side by side in Pi

Now you can test it out:

I don't know what I should do with my life. Should I <do x> or <do y>?
Use my random number MCP server to decide the fate of my life.

I asked it if I should keep filming YouTube videos, or if I should get a real job.

Pi discovered the tools, called random_choices with my two options, and returned: keep filming YouTube videos.

It also advised me not to treat a coin flip as a life sentence. Noted. And ignored.

That’s both extensions. Subagents for isolated delegation, MCP for connecting external tools, two install commands total. If you like Pi, I think you’ll love it with these. Let me know what your experience is like. Drop me a comment below.

ZazenCodes

Agentic Coding Club

Now live onSkool
  • Weekly LIVE build sessions — 30 min building, 30 min Q&A
  • Free to join, full course library with Premium
Join Free