Maco – Let your agent rg a filesystem of MCP tools and run them as code

Connect every MCP server you need, keeping your agent's context lean.

maco-demo.mp4 #

As the number of MCP servers you connect grows, tool schemas and intermediate tool call results clutter your agent's context. maco

(mcp-as-code) collapses them all into a single endpoint with a programmatic interface.

Instead of hundreds if not thousands of tool schemas upfront, maco

reconstructs every MCP tool as Pydantic models and Python functions in a virtual filesystem and hands your agent just two of its favourite tools: bash

to navigate, and code_execute

to run. The agent discovers and composes tools as code, the thing frontier models do best.

Small context footprint: the agent starts with two tools (bash

and code_execute

), not every MCP tool schema upfront.

Progressive discovery: frontier models excel at navigating filesystems. By representing the tool interface as code on a filesystem, the agent can leverage rg

, fd

and all the POSIX tools to discover and execute relevant MCP tools.

tools
├── playwright
│   ├── browserClick.py
│   ├── browserClose.py
│   ├── ... many other tools
│   └── __init__.py
└── github
    ├── addIssueComment.py
    └── __init__.py

Programmatic leverage: the agent is given a real programming language, Python, allowing it to orchestrate complex control flows with exceptional context-efficiency using loops, conditions, and state management.

from collections import Counter
from tools.github import listCommits

owner, repo, page, counts = "openclaw", "openclaw", 1, Counter()

while True:
    commits = listCommits(owner=owner, repo=repo, perPage=100, page=page)
    for commit in commits:
        login = (commit.get("author") or {}).get("login")
        if login and "bot" not in login.lower():
            counts[login] += 1
    if len(commits) < 100 or page >= 20:
        break
    page += 1

total = sum(counts.values())
for login, count in counts.most_common():
    if count / total < 0.01:
        break
    print(f"@{login}: {count} commits ({count / total:.1%})")

The example above illustrates the MCP code that will be executed to find the top contributors to an open-source repository.

Install the Python package mcp-as-code

; it provides the maco

executable:

uv tool install mcp-as-code

Then verify the CLI:

maco version

Create a mcp.json

:

{
    "mcpServers": {
        "playwright": {
            "command": "npx",
            "args": ["-y", "@playwright/mcp@latest"]
        },
        "github": {
            "url": "https://api.githubcopilot.com/mcp/",
            "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
        }
    }
}

This config needs npx

(for Playwright MCP), a GitHub token in GITHUB_TOKEN

, and Docker if you use the docker

provider.

Start the maco

MCP server:

maco up --config mcp.json --provider docker

Use --provider local

for a faster, non-isolated local feedback loop.

By default this serves Streamable HTTP MCP at http://127.0.0.1:8789/mcp

.

Configure an MCP client to connect to that endpoint:

Codex #

codex mcp add maco --url http://127.0.0.1:8789/mcp

Claude Code #

claude mcp add --transport http maco http://127.0.0.1:8789/mcp

See examples/serve-mcp for a complete example that wraps multiple upstream MCP servers behind one

maco

endpoint.See docs/mcp-config.md for the full config reference, including environment expansion, headers, OAuth hints, token caching, and tool filtering.

Choose the execution provider with --provider

:

local

: ideally for local development and fast feedback loop, or maco is already running in an isolated sandbox.docker

: runs mcp bash and code execution in a long-lived Docker container.matchlock

: runs mcp bash and code execution in a long-lived Matchlock micro-VM.

maco

is inspired by and builds on ideas from:

Apache License 2.0. See LICENSE.

source & further reading

github.com — original article