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

Maco, an open-source tool, collapses multiple MCP servers into a single endpoint by representing tools as Python code in a virtual filesystem, reducing agent context footprint. It allows agents to discover and compose tools using bash and code execution, improving efficiency for complex workflows. The tool is available as a Python package and supports local, Docker, and Matchlock execution providers.

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 .