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

> Source: <https://github.com/jingkaihe/maco>
> Published: 2026-06-21 08:35:32+00:00

**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 loading 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.

``` python
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](/jingkaihe/maco/blob/main/examples/serve-mcp) for a complete example that wraps multiple upstream MCP servers behind one

`maco`

endpoint.See [ docs/mcp-config.md](/jingkaihe/maco/blob/main/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](/jingkaihe/maco/blob/main/LICENSE).