FusionAL MCP Server

🚀 FusionAL — Self-Hosted MCP Governance Gateway

Your team connected 10 MCP servers. Now what?
🌐 fusional.dev • 📧 [email protected] • 🗓️ Book a Call

MCP is powerful. Enterprise MCP deployment is a different problem entirely.

Every server you connect loads its full tool manifest into Claude's context window before processing a single token of your request. At 84 tools across several servers, that's 15,540 tokens consumed at session start — before your team has asked anything. At scale, that's cost, latency, and an audit surface nobody can explain to legal.

FusionAL is a self-hosted MCP governance gateway that sits between your AI clients and your tool servers. One endpoint. Central auth. Tool-level policy enforcement. Full audit trail. Deployable in a single Docker command — including on Windows, where MCP has 6 documented failure modes the official docs don't cover.

Built for teams that have already said yes to MCP and now need to run it safely:

• Token control — filter tool exposure per client so context bloat doesn't scale with your server count
• Audit-ready operations — every tool call logged with caller, input, latency, and response status
• Policy enforcement — control what tools run, for whom, and under what conditions
• Windows-hardened — 6 documented failure modes solved, none of which appear in official MCP docs
• AI-powered server generation — describe a tool in plain English, FusionAL builds and registers it
• Done-for-you option — we deploy, govern, and manage it for you

The question isn't whether to adopt MCP. It's whether your deployment will survive contact with your security team.

---

⚡ Quick Start (5 Minutes)

Prerequisites

• Docker Desktop (installed and running)
• Claude Desktop
• Python 3.11+
• Git

Step 1: Clone & Install

git clone https://github.com/JRM-FusionAL/FusionAL.git
cd FusionAL

python -m venv venv
source venv/bin/activate        # macOS/Linux
# venv\Scripts\activate         # Windows

pip install -r core/requirements.txt

Step 2: Start FusionAL

cd core
python -m uvicorn main:app --reload --port 8009

Verify it's running:

curl http://localhost:8009/health

Step 3: Configure Claude Desktop

Find your config file:

• Windows: C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

⚠️ Windows users: Do NOT use %APPDATA% in the path — Claude Desktop won't expand it. Hardcode the full path. Example: C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json

Add FusionAL as an MCP server:

{
  "mcpServers": {
    "fusional-gateway": {
      "url": "http://localhost:8009/sse"
    }
  }
}

Step 4: Restart Claude Desktop & Test

Fully quit and reopen Claude Desktop. Open a new chat and try:

"Generate a Python MCP server that fetches the current weather for a given city."

FusionAL will generate, register, and run it automatically.

---

🐳 Docker Deploy

Build and run the full gateway in Docker:

docker build -t fusional .
docker run -d -p 8089:8009 --name fusional fusional

Or with Docker Compose:

docker compose up -d

Gateway available at http://localhost:8089.

---

🏗️ Architecture

Claude Desktop / Any MCP Client
         │
         ▼  (SSE or Streamable HTTP)
  FusionAL Gateway  (:8009)
         │
   ┌─────┴──────┐
   ▼            ▼
FastAPI      MCP Transport (/mcp)
REST API     ├── execute_code
             ├── generate_and_execute
             └── generate_mcp_project
         │
         ▼
  Docker Sandbox Executor
  (network isolated, memory capped)
         │
         ▼
  MCP Server Registry (JSON)
  ├── business-intelligence-mcp  (:8101)
  ├── api-integration-hub        (:8102)
  └── content-automation-mcp     (:8103)

MCP Tools (via /mcp)

Tool	Description
execute_code	Run Python in an isolated subprocess sandbox
generate_and_execute	Plain English prompt → Claude writes it → runs it
generate_mcp_project	Describe an MCP server → Claude builds the full project

REST API

Endpoint	Method	Description
/health	GET	Health check
/execute	POST	Execute Python (optional Docker sandbox)
/register	POST	Register an MCP server in the registry
/catalog	GET	List all registered servers
/generate	POST	Generate and launch a new server from a prompt

---

🛠️ Showcase Servers

These servers ship with the mcp-consulting-kit and are pre-registered in the FusionAL gateway:

Server	Port	Tools
business-intelligence-mcp	8101	Natural language → SQL (PostgreSQL, MySQL, SQLite)
api-integration-hub	8102	Slack, GitHub Issues, Stripe customer lookup
content-automation-mcp	8103	Web scraping, link extraction, table parsing, RSS feeds

Start the full showcase stack:

cd ../mcp-consulting-kit
docker compose up -d

---

🔒 Security Model

Docker Sandbox

Each code execution runs with:

• ✅ Network isolation (--network none)
• ✅ Memory limits (default 128 MB, configurable)
• ✅ Process limits (max 64 processes)
• ✅ Read-only filesystem (except /tmp)
• ✅ No privilege escalation
• ✅ Non-root user execution

API Security (optional)

When mcp-consulting-kit/showcase-servers/common/security.py is present, the gateway enables:

• API key authentication on /execute, /register, /generate
• Rate limiting
• CORS configuration

---

🪟 Windows-Specific Fixes

FusionAL documents and solves 6 Windows MCP failure modes not covered in official docs:

1. The 60-Second Silence — Claude Desktop times out with zero error. Caused by Docker socket init lag.
   Read the fix →

2. The BOM Trap — Notepad/VS Code injects a byte-order mark into JSON configs, silently breaking MCP.
   Fix: [System.IO.File]::WriteAllText(path, content, New-Object System.Text.UTF8Encoding($false))

3. The Backslash Trap — Windows path separators in claude_desktop_config.json break startup silently.
   Use forward slashes or escaped double backslashes.

4. %USERPROFILE% expansion — Claude Desktop does NOT expand env vars in config paths. Hardcode them.

5. Docker named pipe failure — Docker's named pipe transport fails on WSL2. Use /var/run/docker.sock.

6. Registry timeout at 8+ servers — Claude Desktop hits a timeout threshold on lower-end hardware.
   Cap your registry at 8 servers on i5/i7 7th gen and below.

---

🧰 Building Your Own MCP Server

Using the AI Builder (via Claude Desktop)

After connecting FusionAL, ask Claude:

"Generate an MCP server that queries our PostgreSQL database using natural language."

FusionAL generates the full project, builds it, and registers it in the gateway automatically.

Manual Server Structure

my-server/
├── Dockerfile
├── requirements.txt
├── my_server.py       ← FastMCP tools go here
└── .env

Key Rules

1. Use @mcp.tool() decorators on async functions
2. Single-line docstrings only (multi-line breaks some MCP clients)
3. Return formatted strings from all tools
4. Default parameters to "" not None
5. Log to sys.stderr
6. Run as non-root in Docker

from mcp.server.fastmcp import FastMCP
import sys

mcp = FastMCP("my-server")

@mcp.tool()
async def my_tool(query: str = "") -> str:
    """What this tool does in one line."""
    return f"✅ Result for: {query}"

if __name__ == "__main__":
    mcp.run(transport='stdio')

---

📚 Examples

Example	Path	What it demonstrates
Dice Roller	examples/dice-roller/	D&D dice (8 tools), dice notation parsing
Weather API	examples/weather-api/	External API integration, error handling
File Utils	examples/file-utils/	Safe filesystem access, pagination

---

🚀 Done-for-You Consulting

Don't want to self-manage? FusionAL offers done-for-you MCP deployments:

Tier	Scope	Price
Starter Install	Single environment, core servers, Windows hardening	$2,500–$3,500
Core Install	Full stack, custom servers, governance layer, team onboarding	$5,000–$9,000
Retainer	Ongoing ops, incident response, new server builds	$1,500–$4,000/mo

Book a free 15-min MCP security audit →

---

🤝 Contributing

Contributions welcome. Priority areas:

• New example servers
• Windows compatibility fixes
• Documentation improvements
• Test coverage

---

📄 License

MIT — see LICENSE

---

🙏 Credits

• Anthropic — Claude AI + MCP protocol
• FastAPI — API framework
• FastMCP — MCP server framework
• Docker — Container infrastructure

---

Built by a self-taught developer who fixed the MCP problems nobody else documented.
🌐 fusional.dev • ⭐ Star the repo if it saved you hours

---

🙌 Origin & Inspiration

FusionAL started with a NetworkChuck video.

If you haven't watched "you need to learn MCP RIGHT NOW!!" — go watch it first. Chuck explains the fundamentals better than anyone, and his docker-mcp-tutorial repo is the best starting point for understanding how MCP servers work with Docker.

The dice-roller example and quick-start structure in this repo are adapted from that tutorial (MIT licensed).

Where FusionAL goes further:

Chuck's tutorial shows you how to build MCP servers manually — edit a prompt template, paste it into Claude, implement the result yourself.

FusionAL removes the human from that loop entirely. Instead of a prompt file you copy-paste, generate_mcp_project is a live tool call — Claude describes what it wants built, FusionAL generates it, registers it, and runs it. No clipboard. No manual steps.

More importantly, Chuck's video covers Docker's MCP catalog — 300+ servers you can enable with a click. That's step one. FusionAL is what you need when a CTO asks:

"Great — but how do we audit what those tools are doing? How do we enforce policy? How do we make sure this doesn't become a security incident?"

That's the gap FusionAL was built to fill: governance, auditability, and operational control for teams deploying MCP at scale — especially on Windows, where the catalog alone isn't enough.