Skip to main content
Glama

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

Related MCP server: project-mcp-tools

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.

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

Available Tools

9 tools
approve_toolB

Approve a reviewed draft or tested tool version so it becomes available for search and execution. Use this only after a human or authorized approval workflow has confirmed the tool is safe and useful.

Inputs: tool_id (required), version (required), approved_by (required), notes. Returns: object

deprecate_toolA

Mark a ToolForge tool as deprecated so it remains visible for history and audit purposes but is no longer recommended or used by default. Use this when a tool is obsolete, replaced, unsafe for normal use, or no longer preferred.

Inputs: reason (required), tool_id (required). Returns: object

get_toolA

Get detailed metadata for a ToolForge tool, including description, tags, lifecycle status, versions, active approved version, checksum, approval state, and usage history. Use this before running, approving, updating, deprecating, or explaining a tool.

Inputs: tool_id (required). Returns: object

list_toolsA

List ToolForge tools with optional filters such as status, tag, language, or name. Use this to browse the registry, inspect available capabilities, or find tools before choosing one to view, approve, update, or run.

Inputs: tag, name, status, language. Returns: result

register_toolB

Register a new reusable Python script as a draft ToolForge tool. Use this when an agent or user has created a useful script that should be saved for review, approval, versioning, and future reuse.

Inputs: code (required), name (required), tags (required), language (required), +2 more. Returns: object

rollback_toolA

Restore an earlier approved version of a ToolForge tool as the active version. Use this when a newer approved version is broken, unsafe, or less reliable than a previous approved version.

Inputs: tool_id (required), target_version (required). Returns: object

run_toolA

Execute an approved ToolForge tool with JSON input and return JSON output. Use this when the correct approved tool has been selected and the task should be performed through a governed, logged execution.

Inputs: tool_id (required), input_json (required). Returns: object

search_toolsA

Search approved reusable ToolForge tools by intent, task description, name, tags, or capability. Uses semantic search with keyword and tag fallback. Use this before generating new code when an existing approved tool may already solve the task.

Inputs: query (required), limit, include_deprecated. Returns: result

update_toolA

Create a new draft version of an existing ToolForge tool with updated code and a changelog. Use this when a tool needs a bug fix, improvement, new behavior, or compatibility update without replacing the current approved version immediately.

Inputs: tool_id (required), version (required), new_code (required), changelog (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose covering the full tool lifecycle: registering, viewing, listing, searching, running, approving, deprecating, updating, and rolling back. No two tools have overlapping responsibilities.

    Naming Consistency4/5

    All tools follow a verb_noun pattern (e.g., approve_tool, get_tool), though there is a minor inconsistency between singular 'tool' and plural 'tools' in names like list_tools and search_tools vs others.

    Tool Count5/5

    9 tools is well-scoped for a tool registry server, covering all necessary operations without unnecessary bloat. Each tool serves a distinct and necessary function.

    Completeness4/5

    The tool surface covers the core lifecycle: registration, update, approval, execution, deprecation, and rollback. Minor gaps exist, such as the absence of a reject or unapprove operation, but overall it is fairly complete.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to manage, search, plan, and execute reusable skills while automatically enforcing always-on coding and reasoning guidelines. It provides workflow orchestration, permission-controlled execution, dynamic skill registration, and feedback-based ranking.
      9
      20 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables agents to securely discover and invoke a centrally governed catalog of tools from distributed internal and external providers, with policy enforcement, quotas, inspection, and audit controls.
      -