ToolForge MCP

ToolForge MCP is a governed registry of reusable Python tools for AI agents. It lets agents search approved tools by intent, run approved tools with JSON input, register newly generated scripts as drafts, and manage tool lifecycle through approval, updates, deprecation, and rollback.

The MVP is MCP-only. It runs over stdio by default and does not include a web UI or HTTP server.

Features

• Register Python scripts as draft reusable tools
• Approve reviewed tool versions for execution
• Search approved tools by semantic-style intent with keyword/tag fallback
• Run approved tools through a subprocess JSON contract
• Log every run to SQLite
• Seed safe default tools on first startup
• Update, deprecate, and rollback tool versions

Runtime Paths

By default, ToolForge stores metadata and runtime tool files locally:

data/toolforge.db
tools/

Override these paths with:

export TOOLFORGE_DB_PATH=/path/to/toolforge.db
export TOOLFORGE_TOOLS_DIR=/path/to/tools
export TOOLFORGE_WORK_DIR=/path/to/work

MCP Server

Run the server with:

uv run toolforge-mcp

or:

python3 server.py

Connect MCP Clients

ToolForge MCP is a local stdio MCP server. The MCP client starts the process, then discovers the server instructions and available tools at connection time.

Use absolute paths in client configuration so the server can start from any working directory. Replace /absolute/path/to/toolforge-mcp with your local checkout path.

Recommended Setup

Install runtime dependencies before connecting a client:

cd /absolute/path/to/toolforge-mcp
uv sync --extra dev

The --extra dev option installs test dependencies and optional libraries used by the default seed tools, such as PDF and image helpers. Local semantic embeddings are optional because they pull a larger ML dependency stack. To enable them, run:

uv sync --extra dev --extra semantic

If you do not use uv, create a Python environment and install the package dependencies from pyproject.toml.

Codex

Codex reads MCP servers from ~/.codex/config.toml, or from a project-scoped .codex/config.toml in trusted projects. The Codex CLI and IDE extension share this configuration.

CLI setup:

codex mcp add toolforge --env TOOLFORGE_DB_PATH=/absolute/path/to/toolforge-mcp/data/toolforge.db --env TOOLFORGE_TOOLS_DIR=/absolute/path/to/toolforge-mcp/tools --env TOOLFORGE_WORK_DIR=/absolute/path/to/toolforge-mcp/work -- uv --directory /absolute/path/to/toolforge-mcp run toolforge-mcp

Equivalent ~/.codex/config.toml entry:

[mcp_servers.toolforge]
command = "uv"
args = ["--directory", "/absolute/path/to/toolforge-mcp", "run", "toolforge-mcp"]
startup_timeout_sec = 20
tool_timeout_sec = 120

[mcp_servers.toolforge.env]
TOOLFORGE_DB_PATH = "/absolute/path/to/toolforge-mcp/data/toolforge.db"
TOOLFORGE_TOOLS_DIR = "/absolute/path/to/toolforge-mcp/tools"
TOOLFORGE_WORK_DIR = "/absolute/path/to/toolforge-mcp/work"

In the Codex TUI, run /mcp to confirm that toolforge is connected.

Claude Code

Claude Code can add local stdio MCP servers with claude mcp add. The -- separator is important: everything after it is the command used to start the MCP server.

CLI setup:

claude mcp add \
  --env TOOLFORGE_DB_PATH=/absolute/path/to/toolforge-mcp/data/toolforge.db \
  --env TOOLFORGE_TOOLS_DIR=/absolute/path/to/toolforge-mcp/tools \
  --env TOOLFORGE_WORK_DIR=/absolute/path/to/toolforge-mcp/work \
  --transport stdio \
  toolforge \
  -- uv --directory /absolute/path/to/toolforge-mcp run toolforge-mcp

Project-scoped .mcp.json example:

{
  "mcpServers": {
    "toolforge": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/toolforge-mcp", "run", "toolforge-mcp"],
      "env": {
        "TOOLFORGE_DB_PATH": "/absolute/path/to/toolforge-mcp/data/toolforge.db",
        "TOOLFORGE_TOOLS_DIR": "/absolute/path/to/toolforge-mcp/tools",
        "TOOLFORGE_WORK_DIR": "/absolute/path/to/toolforge-mcp/work"
      },
      "timeout": 120000
    }
  }
}

Inside Claude Code, use /mcp to inspect server status. Project-scoped MCP servers may require workspace trust approval before they become active.

Cursor

Cursor reads MCP servers from JSON configuration. Use a project-scoped .cursor/mcp.json when ToolForge should be available only for this repository, or a user-level MCP configuration when you want it available across projects.

Project-scoped .cursor/mcp.json example:

{
  "mcpServers": {
    "toolforge": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/toolforge-mcp", "run", "toolforge-mcp"],
      "env": {
        "TOOLFORGE_DB_PATH": "/absolute/path/to/toolforge-mcp/data/toolforge.db",
        "TOOLFORGE_TOOLS_DIR": "/absolute/path/to/toolforge-mcp/tools",
        "TOOLFORGE_WORK_DIR": "/absolute/path/to/toolforge-mcp/work"
      }
    }
  }
}

After editing Cursor MCP settings, reload Cursor or restart the agent session, then confirm that the ToolForge tools appear in Cursor's MCP/tools panel.

Without uv

If uv is not available, install the project into a virtual environment and use that environment's Python directly:

cd /absolute/path/to/toolforge-mcp
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -e ".[dev]"
# Optional semantic embeddings:
# python3 -m pip install -e ".[dev,semantic]"

Then replace the MCP command with:

{
  "command": "/absolute/path/to/toolforge-mcp/.venv/bin/python",
  "args": ["/absolute/path/to/toolforge-mcp/server.py"]
}

Agent Governance Pack

ToolForge includes copy-ready governance examples for teams that want Codex, Claude Code, and Cursor to consistently reuse MCP tools instead of creating throwaway scripts.

See governance/ for:

• Codex AGENTS.md guidance and config.toml MCP example
• Claude Code CLAUDE.md guidance and .mcp.json example
• Cursor .mdc rule and .cursor/mcp.json example

The shared policy is:

1. Search ToolForge before creating utility scripts.
2. Run an approved tool when one exists.
3. Register newly generated reusable utility scripts as draft tools.
4. Approve tools only after human or authorized workflow review.

Setup Script

Use the setup script to install project-scoped governance and MCP config for Codex, Claude Code, and Cursor. Running the script without arguments prints help and does not write files:

python3 scripts/setup_agent_governance.py

Pass explicit options to install governance/config files:

python3 scripts/setup_agent_governance.py \
  --agents all \
  --target-project /path/to/your/project \
  --toolforge-dir /absolute/path/to/toolforge-mcp

Preview changes without writing files:

python3 scripts/setup_agent_governance.py --agents all --target-project /path/to/your/project --dry-run

Configure one agent at a time:

python3 scripts/setup_agent_governance.py --agents codex --target-project /path/to/your/project
python3 scripts/setup_agent_governance.py --agents claude --target-project /path/to/your/project
python3 scripts/setup_agent_governance.py --agents cursor --target-project /path/to/your/project

The script updates managed ToolForge sections idempotently and preserves other MCP servers in JSON config files.

Stored Tool Contract

Stored scripts must:

• read one JSON object from stdin
• write one JSON object to stdout
• exit nonzero on failure

Default Seed Tools

On first startup, ToolForge seeds these approved tools:

• validate_json_schema
• clean_csv_file
• generate_markdown_report
• resize_image
• extract_text_from_pdf

The seed operation is idempotent and recorded in SQLite.

License

Apache License 2.0