MCP Fusion is a framework that helps you build AI-native MCP servers with a clean separation of concerns: Model (validated with Zod schemas), Presenter (egress firewall shaping what the LLM can see), and Agent (the LLM itself). It provides a fluent API for defining tools (queries, mutations, actions) and automatic type-safe routing, along with a real-time inspector and a suite of adapters and generators. With Fusion, you can scaffold tools from the filesystem (file-based routing under src/tools/), test pipelines in-memory, and govern access with a lockfile and entitlements. The built-in Inspector gives you a real-time dashboard to observe available tools, request traffic, and deep-dive into tool performance. It also ships with a tRPC-style client surface for compile-time route validation and autocomplete, making it easy to build and maintain complex tool sets for LLM-driven workflows.

To use the server locally, install the MCP Fusion package and run the command to start the server. You’ll be able to define tools with the fluent API (f.query, f.mutation, f.action), create presenters to shape data returned to the LLM, and rely on the Governance features (lockfiles, attestation, and diffing) to keep your surface area secure. Tools appear automatically via the file-based routing convention (drop a file in src/tools/ and it becomes a usable tool). The inspector can connect to the running server via Shadow Socket to observe live traffic, tool registry, and performance metrics.

Prerequisites:

• Node.js 16+ (recommended: latest LTS) and npm/yarn installed
• Basic familiarity with TypeScript and MCP concepts (Model → Presenter → Agent)

Steps:

1. Install Node.js from https://nodejs.org/ and verify: node -v npm -v

2. Install the MCP Fusion package (as a project dependency or global helper): npm install @vinkius-core/mcp-fusion

   or if you prefer using npx directly without a local install:

   npm install -D @vinkius-core/mcp-fusion

3. Initialize a new server scaffold (optional but recommended): npx fusion create my-server cd my-server

   This will scaffold a minimal MCP Fusion project with file-based routing

4. Start the server (examples): npx fusion dev

   or if you installed locally: npx @vinkius-core/mcp-fusion dev

5. Verify the server is running by visiting the inspector or API endpoints as documented in the project docs.

Note: If you’re integrating into an existing project, you can import and initialize the Fusion runtime in your app entry point and wire up tools under src/tools/ as needed.

Tips and common considerations:

• Use the Inspector (npx fusion inspect) to auto-discover tools and observe runtime metrics. The Shadow Socket connection can help avoid stdio interference while debugging.
• Tools live under src/tools/ via file-based routing; keep your tools organized and versioned to leverage the governance and diffing capabilities.
• Enable and configure the governance lockfile (mcp-fusion.lock) to control capabilities and entitlements across environments.
• If you need to customize the runtime environment, you can set environment variables for inspector ports, cache policies, and LLM interaction constraints (refer to the docs for supported vars).
• For TypeScript projects, enjoy the strong typing on f.query/f.mutation/f.action and the inferred router types for end-to-end type-safety.
• If you plan to deploy to edge environments (Vercel, Cloudflare Workers), explore the ecosystem adapters mentioned in the docs.