ToolForge MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ToolForge MCP find a tool that converts markdown to HTML"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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/workMCP Server
Run the server with:
uv run toolforge-mcpor:
python3 server.pyConnect 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 devThe --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 semanticIf 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-mcpEquivalent ~/.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-mcpProject-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.mdguidance andconfig.tomlMCP exampleClaude Code
CLAUDE.mdguidance and.mcp.jsonexampleCursor
.mdcrule and.cursor/mcp.jsonexample
The shared policy is:
Search ToolForge before creating utility scripts.
Run an approved tool when one exists.
Register newly generated reusable utility scripts as draft tools.
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.pyPass 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-mcpPreview changes without writing files:
python3 scripts/setup_agent_governance.py --agents all --target-project /path/to/your/project --dry-runConfigure 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/projectThe 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_schemaclean_csv_filegenerate_markdown_reportresize_imageextract_text_from_pdf
The seed operation is idempotent and recorded in SQLite.
License
Apache License 2.0
Available Tools
9 toolsapprove_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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
One place to build, share, and govern the skills and tools your AI agents use at work.
A registry of AI agent tools — MCP servers, APIs, CLIs, SDKs — kept current by automated ingestion.
Register, deploy, review, and govern internal applications built with coding agents.
Governed AI agent skills — one library, distributed to devs and exposed to remote agents over MCP.
Related MCP Servers
- FlicenseAqualityCmaintenanceCentral registry for AI tools with vector search and knowledge graph, enabling intelligent tool discovery, chaining, and execution via MCP.12-
- AlicenseAqualityBmaintenanceA Python framework that exposes developer tools through MCP, REST API, and CLI from a single shared registry, enabling AI assistants, HTTP clients, and terminal users to access the same tools.12GPL 3.0
- AlicenseAqualityDmaintenanceEnables 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.920 npm1MIT
- FlicenseNot gradedqualityDmaintenanceEnables 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.-