forage

Forage is a gateway MCP server that lets your AI agent discover, install, and learn to use new tools automatically. When an agent encounters a task it can't complete, Forage searches registries in parallel, installs the appropriate tool, and exposes its capabilities to the agent without requiring a restart. Tools are started as proxied subprocesses, and their commands are wrapped so the agent can call them as if they were native MCP tools. This enables a continually expanding toolbox that persists across sessions, with Forage automatically starting previously installed tools on startup. You can use the built-in CLI to search, list, initialize, and manage tools, or query the installed tools through the agent’s MCP interface once they’re registered by Forage.

Prerequisites:

• Node.js (recommended latest LTS) and npm installed on your system.
• Basic familiarity with MCP concepts and how your agent loads tools.

Install (optional global install):

1. Install the Forage MCP package globally so you can run it from any shell:

npm install -g forage-mcp

Run locally (no global install required): 2) Start the Forage MCP server via npx (no installation required beyond npm):

npx -y forage-mcp

Usage notes:

• For Claude Code or Cursor setups, you typically add the server via your agent’s MCP manager, e.g.:

claude mcp add forage -- npx -y forage-mcp

• For Mirage-like environments or scripts, you can start Forage and then install additional tools as needed using forage_install.

If you prefer not to rely on npx every time, you can install forage-mcp globally as shown above and then run the forage-mcp command directly.

Notes and tips:

• Forage acts as a gateway: it discovers tools from the Official MCP Registry, Smithery, and npm in parallel and starts them as child processes. Tools are then registered under a namespaced name (foraged__<server>__<tool>).
• All installs require explicit user approval when using forage_install from the agent UI or CLI to protect against untrusted code.
• Forage stores its state under ~/.forage/ (manifest.json, install-log.json, and a cache folder). On startup it auto-starts previously installed tools.
• Environment variables for tools are passed at install time and are not persisted in the tool’s configuration. This helps keep secrets out of persistent config.
• The CLI supports search, listing installed tools, and initializing the client for a particular agent (Claude Code or Cursor).
• If you encounter issues with a tool, check the install-log.json in ~/.forage for a detailed audit trail of installs and uninstalls.