{"slug": "maco-let-your-agent-rg-a-filesystem-of-mcp-tools-and-run-them-as-code", "title": "Maco – Let your agent rg a filesystem of MCP tools and run them as code", "summary": "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.", "body_md": "**Connect every MCP server you need, keeping your agent's context lean.**\n\n## maco-demo.mp4\n\nAs the number of MCP servers you connect grows, tool schemas and intermediate tool call results clutter your agent's context. `maco`\n\n(mcp-as-code) collapses them all into a single endpoint with a programmatic interface.\n\nInstead of loading hundreds if not thousands of tool schemas upfront, `maco`\n\nreconstructs every MCP tool as Pydantic models and Python functions in a virtual filesystem and hands your agent just two of its favourite tools: `bash`\n\nto navigate, and `code_execute`\n\nto run. The agent discovers and composes tools as code, the thing frontier models do best.\n\n**Small context footprint:** the agent starts with two tools (`bash`\n\nand `code_execute`\n\n), not every MCP tool schema upfront.\n\n**Progressive discovery:** frontier models excel at navigating filesystems. By representing the tool interface as code on a filesystem, the agent can leverage `rg`\n\n, `fd`\n\nand all the POSIX tools to discover and execute relevant MCP tools.\n\n```\ntools\n├── playwright\n│   ├── browserClick.py\n│   ├── browserClose.py\n│   ├── ... many other tools\n│   └── __init__.py\n└── github\n    ├── addIssueComment.py\n    └── __init__.py\n```\n\n**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.\n\n``` python\nfrom collections import Counter\nfrom tools.github import listCommits\n\nowner, repo, page, counts = \"openclaw\", \"openclaw\", 1, Counter()\n\nwhile True:\n    commits = listCommits(owner=owner, repo=repo, perPage=100, page=page)\n    for commit in commits:\n        login = (commit.get(\"author\") or {}).get(\"login\")\n        if login and \"bot\" not in login.lower():\n            counts[login] += 1\n    if len(commits) < 100 or page >= 20:\n        break\n    page += 1\n\ntotal = sum(counts.values())\nfor login, count in counts.most_common():\n    if count / total < 0.01:\n        break\n    print(f\"@{login}: {count} commits ({count / total:.1%})\")\n```\n\nThe example above illustrates the MCP code that will be executed to find the top contributors to an open-source repository.\n\nInstall the Python package `mcp-as-code`\n\n; it provides the `maco`\n\nexecutable:\n\n```\nuv tool install mcp-as-code\n```\n\nThen verify the CLI:\n\n```\nmaco version\n```\n\nCreate a `mcp.json`\n\n:\n\n```\n{\n    \"mcpServers\": {\n        \"playwright\": {\n            \"command\": \"npx\",\n            \"args\": [\"-y\", \"@playwright/mcp@latest\"]\n        },\n        \"github\": {\n            \"url\": \"https://api.githubcopilot.com/mcp/\",\n            \"headers\": { \"Authorization\": \"Bearer ${GITHUB_TOKEN}\" }\n        }\n    }\n}\n```\n\nThis config needs `npx`\n\n(for Playwright MCP), a GitHub token in `GITHUB_TOKEN`\n\n, and Docker if you use the `docker`\n\nprovider.\n\nStart the `maco`\n\nMCP server:\n\n```\nmaco up --config mcp.json --provider docker\n```\n\nUse `--provider local`\n\nfor a faster, non-isolated local feedback loop.\n\nBy default this serves Streamable HTTP MCP at `http://127.0.0.1:8789/mcp`\n\n.\n\nConfigure an MCP client to connect to that endpoint:\n\n## Codex\n\n```\ncodex mcp add maco --url http://127.0.0.1:8789/mcp\n```\n\n## Claude Code\n\n```\nclaude mcp add --transport http maco http://127.0.0.1:8789/mcp\n```\n\nSee [ examples/serve-mcp](/jingkaihe/maco/blob/main/examples/serve-mcp) for a complete example that wraps multiple upstream MCP servers behind one\n\n`maco`\n\nendpoint.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.\n\nChoose the execution provider with `--provider`\n\n:\n\n`local`\n\n: ideally for local development and fast feedback loop, or maco is already running in an isolated sandbox.`docker`\n\n: runs mcp bash and code execution in a long-lived Docker container.`matchlock`\n\n: runs mcp bash and code execution in a long-lived Matchlock micro-VM.\n\n`maco`\n\nis inspired by and builds on ideas from:\n\nApache License 2.0. See [ LICENSE](/jingkaihe/maco/blob/main/LICENSE).", "url": "https://wpnews.pro/news/maco-let-your-agent-rg-a-filesystem-of-mcp-tools-and-run-them-as-code", "canonical_source": "https://github.com/jingkaihe/maco", "published_at": "2026-06-21 08:35:32+00:00", "updated_at": "2026-06-21 08:38:02.287700+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "large-language-models", "ai-infrastructure"], "entities": ["Maco", "MCP", "Playwright", "GitHub", "Codex", "Claude Code", "Docker", "Matchlock"], "alternates": {"html": "https://wpnews.pro/news/maco-let-your-agent-rg-a-filesystem-of-mcp-tools-and-run-them-as-code", "markdown": "https://wpnews.pro/news/maco-let-your-agent-rg-a-filesystem-of-mcp-tools-and-run-them-as-code.md", "text": "https://wpnews.pro/news/maco-let-your-agent-rg-a-filesystem-of-mcp-tools-and-run-them-as-code.txt", "jsonld": "https://wpnews.pro/news/maco-let-your-agent-rg-a-filesystem-of-mcp-tools-and-run-them-as-code.jsonld"}}