/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](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 foun