MCPForge MCP server

⚒️ MCPForge

Build MCP tools visually. Connect any database. Ship to AI instantly.

MCPForge is an open-source, self-hostable platform that turns any database (or HTTP API) into Model Context Protocol (MCP) tools your AI clients (Claude, Cursor, …) can call — without writing a custom MCP server from scratch.

Think of it as Apollo Studio for MCP: connect a database, write a query (or let the built-in AI copilot write it for you), define typed parameters, and your tools are live over MCP immediately — no restart.

📚 Full docs: Features · Documentation

---

✨ Highlights

• 🔌 Multi-database — SQL Server, MySQL, PostgreSQL, MongoDB
• ✏️ Four tool modes — sql, code (JS), api (HTTP), multi (cross-DB) — all with {{param}} interpolation bound safely per engine
• 🧠 Monaco editor + schema browser + visual query builder
• 🤖 AI Assistant — an agentic copilot (Anthropic · OpenAI · Ollama) that reads your data and builds & manages tools by chat, with streaming replies and a "Show thinking" trace
• 🔄 Hot reload — tool changes reach MCP clients on their next connection, no restart
• 🕑 Versioning & rollback — every tool change is snapshotted; restore in one click
• 🧾 Audit log — every create/update/delete/restore (by you or the AI) is recorded
• 🔐 Secure by default — JWT login + per-workspace roles, AES-256-GCM credentials, read-only connections, SSRF egress guard, sandboxed code mode, outbound timeouts, rate limits
• 👥 Owned & shared workspaces — own a workspace, share it as viewer/editor/admin, and issue scoped MCP API keys (per-tool, read/write/both — hashed at rest, shown once)
• 📦 Import/export tools as JSON · 🐳 Docker-ready · 🔑 Per-workspace API keys for MCP clients

See features.md for the complete catalogue.

---

🚀 Quick Start

With Docker (recommended)

git clone <repo-url> mcpforge
cd mcpforge

cp backend/.env.example backend/.env
# Edit backend/.env — set JWT_SECRET and ENCRYPTION_KEY (≥32 chars)

docker compose up -d --build    # starts the backend + MongoDB

The backend runs at http://localhost:3000 (check http://localhost:3000/health). Compose reads backend/.env and points the backend at the bundled MongoDB automatically, so MONGODB_URI in that file is ignored under Docker.

The Studio isn't containerised — run it from studio/ (npm install && npm run dev, or npm run build for a static bundle) and open it in your browser.

Without Docker

Backend (needs a running MongoDB):

cd backend
npm install
cp .env.example .env            # set MONGODB_URI, JWT_SECRET, ENCRYPTION_KEY
npm run dev                     # http://localhost:3000

Studio (in a second terminal):

cd studio
npm install
npm run dev                     # http://localhost:5173

One terminal instead of two? After installing both (npm run install:all), run npm run dev from the repo root to start the backend and Studio together — see Development.

First visit shows a registration form — the first account you create becomes the admin and bootstraps the instance (registration then closes unless ALLOW_REGISTRATION=true). Full setup notes: documentation.md.

---

🧭 How it works

┌──────────────┐     /api/* (JWT)        ┌──────────────────────────────┐
│  Studio (UI) │ ───────────────────────▶│  Backend (Express)           │
└──────────────┘                         │   ├─ REST controllers         │
                                         │   ├─ MCP runtime (/mcp/*)     │──▶ MongoDB (config)
┌──────────────┐  /mcp/:slug/sse         │   ├─ AI agent loop            │
│  AI client   │ ───(x-api-key)─────────▶│   └─ DB drivers / LLM adapters│──▶ Your DBs + AI providers
│ (Claude etc.)│                         └──────────────────────────────┘
└──────────────┘

• Backend (backend/) — Node.js ESM · Express · Mongoose. REST API for the Studio, the dynamic MCP runtime, and the AI agent loop. Config lives in MongoDB.
• Studio (studio/) — Vite · React 18 · Tailwind. The web UI.

Architecture deep-dive: documentation.md.

---

📡 Connecting to Claude (and other MCP clients)

Create a workspace, add tools, then point your client at the workspace's MCP URL using its API key (both shown on the MCP Endpoint page):

{
  "mcpServers": {
    "my-erp": {
      "url": "http://localhost:3000/mcp/my-workspace/sse",
      "headers": { "x-api-key": "mcpf_your_api_key_here" }
    }
  }
}

Only enabled tools are exposed; editing tools applies on the client's next connection. More: documentation.md.

---

🔧 Tool examples

SQL mode

{
  "name": "get_employees",
  "description": "Fetch active employees by department",
  "mode": "sql",
  "query": "SELECT * FROM HR_Employee WHERE Department = {{department}} AND IsActive = 1",
  "params": [{ "name": "department", "type": "string", "required": true }]
}

MongoDB (JSON descriptor)

{
  "name": "get_orders",
  "description": "Recent orders by customer",
  "mode": "sql",
  "query": "{\"collection\":\"orders\",\"operation\":\"find\",\"filter\":{\"customerId\":\"{{customer_id}}\"},\"sort\":{\"createdAt\":-1},\"limit\":50}",
  "params": [{ "name": "customer_id", "type": "string", "required": true }]
}

Code mode (sandboxed JS)

{
  "name": "sales_summary",
  "description": "Total sales grouped by region",
  "mode": "code",
  "query": "const { rows } = await db.query('SELECT Region, SUM(Amount) AS Total FROM Sales WHERE Year = {{year}} GROUP BY Region', { year: params.year }); return rows;",
  "params": [{ "name": "year", "type": "number", "required": true }]
}

Full authoring guide (params, api/multi modes, dialect notes): documentation.md.

---

🤖 AI Assistant

A copilot in every workspace that can inspect your schema, run analytical queries, and create/update/test MCP tools by conversation — with streaming responses, @-mentions of connections/tools/workspaces, text & image attachments (vision, for capable models), and a collapsible Show thinking trace of everything it did. Providers (Anthropic / OpenAI / Ollama) are configured globally; API keys are AES-encrypted and never returned to the browser. Details: documentation.md.

---

🛠️ API at a glance

All /api/* routes require a JWT (from /api/auth/login), except /api/auth/*. The /mcp/* runtime uses per-workspace API keys instead.

Area	Examples
Auth	POST /api/auth/register · POST /api/auth/login · GET /api/auth/me
Workspaces	GET/POST /api/workspaces · POST /api/workspaces/:id/rotate-key
Connections	POST …/connections · …/:id/test · …/:id/introspect · …/:id/schema
Tools	POST …/tools · PATCH …/tools/:id · …/:id/test · …/:id/versions · …/versions/:vid/restore
AI	POST …/conversations/:id/messages · …/messages/stream (SSE)
Audit	GET …/audit
MCP	GET /mcp/:slug/sse · POST /mcp/:slug/message

Full reference (every endpoint, bodies, responses, error codes): documentation.md.

---

🔐 Security

• JWT login gates the entire Studio API; passwords bcrypt-hashed.
• Per-workspace access control — ownership + sharing with roles (viewer/editor/admin), plus scoped MCP API keys limited to specific tools and read/write/both (hashed at rest).
• AES-256-GCM-encrypted database credentials and AI provider keys at rest (scrypt-derived key, per-value IV, auth tag); keys are never returned to the client.
• Read-only connections block write/DDL (incl. from the AI agent); MongoDB server-side-JS operators ($where/$function/…) are always rejected.
• SSRF egress guard on api-mode tools — public http(s) hosts only, with every redirect hop re-validated (allowlist via API_TOOL_ALLOW_HOSTS).
• Code mode runs in a node:vm sandbox with a hard timeout (kill switch: CODE_MODE_ENABLED=false).
• Timeouts on all outbound calls (LLM / API / DB) + rate limiting (incl. /mcp/*).

The node:vm sandbox is a soft boundary, and read-only enforcement is keyword-based — pair it with a least-privilege DB user, and run behind HTTPS in production. See documentation.md.

---

⚙️ Configuration

Required backend env: MONGODB_URI, JWT_SECRET, ENCRYPTION_KEY (≥32 chars). Optional: provider keys, registration policy, and timeout/code-mode knobs. Full table: documentation.md.

---

🧪 Development

Run both servers with one command — from the repo root:

npm run install:all    # first time only: installs backend + studio deps
npm run dev            # starts backend (:3000) + Studio (:5173) together

Output from both is shown with [backend]/[studio] prefixes; press Ctrl+C once to stop both. (npm start is an alias.) This is a tiny zero-dependency Node launcher (dev.mjs) — the repo root needs no npm install of its own. The backend still needs its .env + a running MongoDB (see Quick Start).

Or run each app on its own:

# Backend
cd backend && npm run dev      # nodemon on :3000
cd backend && npm test         # node:test unit suite

# Studio
cd studio && npm run dev       # Vite on :5173
cd studio && npm run build     # production build

---

🗺️ Roadmap

• Per-workspace ownership, sharing & roles (viewer/editor/admin)
• Scoped, hashed MCP API keys (per-tool + read/write/both, show-once)
• DNS-pinned egress for api-mode (closes the SSRF rebinding window)
• Bundle Monaco locally (today its runtime lazy-loads from CDN)
• Isolated-process sandbox for code mode (hostile multi-tenant)
• Audio attachments for the AI Assistant
• Webhook triggers · OpenAPI import → auto-generate tools

Already shipped: visual Studio, Monaco editor, AI Assistant (streaming + agentic + vision/image input), JWT auth, read-only connections, tool versioning/rollback, audit log, import/export, Docker, AES-256-GCM credential encryption, SSRF egress guard, workspace ownership/sharing/roles, scoped API keys.

---

📄 License

MIT — free to use, modify, and self-host.

---

New here? Start with features.md for what MCPForge can do, then documentation.md for setup, the API, and how to extend it.