io.github.isaac-levine/forage
Self-improving tool discovery for AI agents. Find, install, and use new MCP servers automatically.
🌿 Forage
Self-improving tool discovery for AI agents.
Install one MCP server. Your agent finds the rest.
npm · GitHub · Contributing
Forage is an MCP server that lets AI agents discover, install, and learn to use new tools — automatically. When an agent hits a wall, it forages for the right tool, installs it, and teaches itself how to use it. No restarts. No manual config. The agent gets permanently smarter.
Why?
AI coding agents are limited to whatever tools they're configured with at session start. Need to query a database? Deploy to Vercel? Search Slack? The agent apologizes and you manually install the right MCP server.
Forage closes that loop:
Agent encounters a task it can't do
→ forage_search("query postgres database")
→ forage_install("@modelcontextprotocol/server-postgres")
→ Tools available IMMEDIATELY (no restart)
→ forage_learn() saves instructions to CLAUDE.md
→ Next session: auto-starts, agent already knows how to use it
Quick Start
Claude Code
claude mcp add forage -- npx -y forage-mcp
Cursor
npx forage-mcp init --client cursor
That's it. Start a new session and Forage is ready.
Tools
| Tool | Description |
|---|---|
forage_search | Search for MCP servers across the Official MCP Registry, Smithery, and npm |
forage_evaluate | Get details on a package — downloads, README, install command |
forage_install | Install and start an MCP server as a proxied subprocess (requires user approval) |
forage_learn | Write usage instructions to CLAUDE.md / AGENTS.md / .cursor/rules/ |
forage_status | List all installed and running tools |
forage_uninstall | Remove a tool and clean up rules |
How It Works
Forage is a gateway/proxy MCP server:
- You install Forage once — it's the only MCP server you configure manually
- Forage discovers tools — searches the Official MCP Registry, Smithery, and npm in parallel
- Forage installs tools — starts them as child processes, wraps their capabilities
- No restart needed — emits
list_changednotifications so the agent picks up new tools instantly - Knowledge persists —
forage_learnwrites to agent rule files, manifest auto-starts tools next session
Architecture
┌─────────────────────────────────────────────┐
│ Claude Code / Cursor / Codex │
│ │
│ "I need to query a Postgres database" │
└──────────────────┬──────────────────────────┘
│ MCP
▼
┌─────────────────────────────────────────────┐
│ Forage MCP Server │
│ │
│ forage_search ─── Official Registry │
│ forage_install Smithery │
│ forage_learn npm │
│ forage_status │
│ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Postgres MCP│ │ GitHub MCP │ ... │
│ │ (subprocess)│ │ (subprocess)│ │
│ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────┘
When you install a tool through Forage:
- Forage runs
npx -y <package>as a child process - Connects to it via
StdioClientTransport(MCP client) - Discovers the child server's tools via
listTools - Re-registers each tool on the Forage server with a namespaced name (
foraged__<server>__<tool>) - Sends
tools/list_changednotification — the agent sees new tools immediately - When the agent calls a proxied tool, Forage forwards the call to the child server
Persistence
Forage stores its state in ~/.forage/:
| File | Purpose |
|---|---|
manifest.json | Installed tools, command/args, auto-start configuration |
install-log.json | Audit trail of all installs and uninstalls |
cache/ | Cached registry search results |
On startup, Forage reads the manifest and auto-starts all previously installed servers. Your agent picks up right where it left off.
CLI
Forage also includes a CLI for humans:
forage search "postgres database" # Search registries
forage list # List installed tools
forage init # Set up for Claude Code
forage init --client cursor # Set up for Cursor
Security
[!IMPORTANT] Forage cannot install tools without explicit user approval. Every
forage_installcall requiresconfirm: true.
- Audit trail — every install/uninstall is logged with timestamps to
~/.forage/install-log.json - No remote backend — everything runs locally. Registry searches are read-only GET requests to public APIs.
- No secrets stored — environment variables for child servers are passed at install time, not persisted.
Development
git clone https://github.com/isaac-levine/forage.git
cd forage
npm install
npm run build
Test locally with Claude Code:
claude mcp add forage-dev -- node /path/to/forage/dist/server.js
See CONTRIBUTING.md for more details.
Roadmap
Features
-
forage update— check for newer versions of installed tools - Support for pip/cargo/brew packages (not just npm)
- Smarter search ranking (weight by downloads, stars, description relevance)
- Auto-configure environment variables from
.envfiles -
forage doctor— diagnose common setup issues
Distribution
- Publish to npm
- Submit to the Official MCP Registry
- Submit to Smithery
- Submit to mcp.so and glama.ai
- Landing page at forage.dev
Community
- Demo GIF / video in README
- Write launch blog post
- Post to r/ClaudeAI, r/LocalLLaMA, Hacker News (Show HN)
- Share in MCP Discord / community channels
- Write use-case guides (e.g. "Add Postgres to Claude Code in 30 seconds")
- Add GitHub Discussions for Q&A and feature requests
License
Installation
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y forage-mcpSet up in your AI client
Merge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-isaac-levine-forage": {
"command": "npx",
"args": [
"-y",
"forage-mcp"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referencePackage
forage-mcpnpmCompatible MCP Clients
io.github.isaac-levine/forage works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
- Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect. - Cursor
~/.cursor/mcp.jsonRestart Cursor for changes to take effect. - VS Code
.vscode/mcp.jsonReload VS Code window for changes to take effect. - Windsurf
~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect. - Claude Code
.mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.