vinkius-deploy

name	vinkius-deploy
description	How to deploy MCP servers to Vinkius Edge using `mcpfusion deploy`. Use this skill whenever deploying, configuring remote settings, preparing an entrypoint for edge deployment, or troubleshooting deploy-related errors. Activate when the user says "deploy", "publish to edge", "mcpfusion deploy", "push to Vinkius", mentions .MCPFusionrc, MCPFUSION_DEPLOY_TOKEN, or any edge deployment topic.
license	Apache-2.0
compatibility	Requires Node.js >= 18, MCP Fusion CLI (included in @mcpfusion/core)
metadata	{"author":"vinkius-labs","version":"1.0","tags":"deploy, edge, cloud, cli"}

Deploying to Vinkius Edge

mcpfusion deploy bundles your MCP server into a self-contained fat bundle, compresses it, and uploads it to Vinkius Edge where it runs inside a V8 Isolate.

Quick Start

# 1. Configure the remote (once per project)
MCP mcpfusion remote --server-id <uuid-from-dashboard>

# 2. Set the deploy token in .env
echo "MCPFusion_DEPLOY_TOKEN=<connection-token-from-dashboard>" >> .env

# 3. Deploy
mcpfusion deploy

The server UUID and connection token are obtained from the Vinkius Cloud dashboard after creating a server instance.

Configuration Files

.MCPFusionrc (auto-generated by mcpfusion remote)

{
  "remote": "https://cloud.vinkius.com",
  "serverId": "abc-123-def"
}

• Auto-added to .gitignore
• remote defaults to https://cloud.vinkius.com (omit to use default)
• serverId is the target server UUID from the dashboard

.env (deploy token)

MCPFUSION_DEPLOY_TOKEN=your-connection-token-here

The token authenticates the deploy request. It can also be passed via --token <value> flag.

Edge Constraints — CRITICAL

V8 Isolates do NOT have filesystem or process access. The following patterns are incompatible with edge deployment:

❌ autoDiscover() — Requires fs.readdir

// WRONG — autoDiscover() scans the filesystem at runtime
await autoDiscover(registry, fileURLToPath(new URL('./tools', import.meta.url)));

// CORRECT — explicit imports for edge
import { listUsers } from './tools/users.js';
import { getInvoice } from './tools/billing.js';
registry.register(listUsers);
registry.register(getInvoice);

❌ SandboxEngine — Requires child_process and fs

SandboxEngine cannot run inside V8 isolates. Remove it for edge deploys — tool code runs directly in the isolate.

❌ Inspector / @mcpfusion/inspector — Requires Node.js IPC

The TUI inspector cannot run inside V8 isolates.

⚠️ fast-redact — Uses Function constructor

May have limited support. Verify it works in your isolate before deploying.

Edge-Compatible Server Entrypoint

See references/example-edge-server.ts for a complete example.

Key differences from a standard server.ts:

- import { autoDiscover } from '@mcpfusion/core';
+ // Explicit imports — no filesystem in V8 isolates
+ import { listProducts } from './tools/product.js';
+ import { getInvoice } from './tools/billing.js';

  const registry = f.registry();
- await autoDiscover(registry, ...);
+ registry.register(listProducts);
+ registry.register(getInvoice);

Deploy Pipeline — What Happens Under the Hood

read .MCPFusionrc + .env
       ↓
resolve entrypoint (src/server.ts → src/index.ts → server.ts → index.ts)
       ↓
check for edge-incompatible APIs (autoDiscover, SandboxEngine, Inspector)
       ↓
esbuild bundle (IIFE, platform: browser, es2022, tree-shaking, minify)
       ↓
size check (max 500KB raw)
       ↓
gzip compress + SHA256 hash
       ↓
POST /servers/:serverId/deploy (Bearer token)
       ↓
response: { deployment_id, server_name, url }

Bundle Characteristics

Property	Value
Format	IIFE (Immediately Invoked Function Expression)
Platform	browser (no Node.js APIs)
Target	ES2022
Max bundle size	500KB (raw, before gzip)
Dependencies	All bundled inside (zod, MCP Fusion, MCP SDK)
Node.js modules	Aliased to edge stubs (AST-compatible, never called)

CLI Reference

mcpfusion deploy

Bundle, compress, and deploy to Edge.

mcpfusion deploy                        # auto-detect entrypoint
mcpfusion deploy --server ./src/app.ts  # explicit entrypoint
mcpfusion deploy --token <token>        # override MCPFUSION_DEPLOY_TOKEN
mcpfusion deploy --allow-insecure       # suppress HTTP plaintext warning

mcpfusion remote

Configure the target server and API endpoint.

MCP mcpfusion remote                              # show current config
MCP mcpfusion remote --server-id <uuid>           # set server ID (uses default cloud)
MCP mcpfusion remote https://custom.api.com       # override API endpoint
MCP mcpfusion remote https://custom.api.com --server-id <uuid>  # both at once

mcpfusion dev

Start HMR dev server with auto-reload (for local development).

mcpfusion dev --server ./src/server.ts
mcpfusion dev --server ./src/server.ts --dir ./src/tools

fusion lock

Generate or validate capability lockfile.

fusion lock                               # generate/update lockfile
fusion lock --check                       # verify (CI gate)

mcpfusion create

Scaffold a new MCP mcpfusion server project.

mcpfusion create my-server
mcpfusion create my-server -y                 # skip prompts
mcpfusion create my-server --vector prisma --transport sse

mcpfusion inspect

Launch the real-time TUI dashboard (requires @mcpfusion/inspector).

mcpfusion inspect --demo            # built-in simulator
fusion insp --pid 12345          # connect to server PID

Troubleshooting

Error	Cause	Fix
run: MCP mcpfusion remote --server-id <uuid>	No .MCPFusionrc or missing serverId	Run mcpfusion remote --server-id <uuid>
set MCPFUSION_DEPLOY_TOKEN=<token> in .env	Token not found	Add token to .env or pass --token
connection token revoked or invalid (401)	Invalid or expired token	Generate a new token in the dashboard
connection token does not belong to this server (403)	Token/server mismatch	Check your server-id matches the token
server not found (404)	Invalid server UUID	Verify the server exists in the dashboard
bundle too large: NNNkb (max 500KB)	Fat bundle exceeds limit	Remove unused imports, check tree-shaking
autoDiscover() uses fs.readdir	Edge-incompatible API	Switch to explicit registry.register()
DNS resolution failed	Wrong remote URL	Check mcpfusion remote config
connection refused	API not running	Verify the remote URL is reachable

Entrypoint Auto-Detection

When --server is not provided, the CLI probes these paths in order:

1. src/server.ts
2. src/index.ts
3. src/server.js
4. src/index.js
5. server.ts
6. index.ts
7. server.js
8. index.js