MCP Client Configuration

Configure MCP clients to connect to your FrontMCP server using stdio, HTTP, or Unix socket transport. This guide covers every supported connection mode and client.

Quick Reference

Transport	Best For	Config Key	Server Command
Stdio	npm packages, local binaries	`command` + `args`	`my-app --stdio`
HTTP	Remote servers, cloud deployments	`url`	`my-app serve -p 3000`
Unix Socket	Local daemons, low-latency	`url` + `socketPath`	`my-app daemon start`

Stdio Transport

Stdio is the most common transport for MCP servers. The client spawns your server as a child process and communicates via stdin/stdout using JSON-RPC 2.0. No network setup required.

In stdio mode, stdout is reserved for MCP protocol messages. All logs are automatically redirected to stderr and ~/.frontmcp/logs/. You don’t need to configure anything — FrontMCP handles this automatically when --stdio is passed.

Using npx (npm package)

The simplest way to distribute your MCP server. Publish to npm, then users can run it with npx:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-frontmcp-server", "--stdio"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

Using a Local Binary

If you built your server with frontmcp build --target cli, point directly to the binary:

{
  "mcpServers": {
    "my-server": {
      "command": "/usr/local/bin/my-server",
      "args": ["--stdio"]
    }
  }
}

Using Node.js Directly

Run the JS bundle directly with Node.js:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/my-server.bundle.js", "--stdio"]
    }
  }
}

With Environment Variables

Pass configuration via environment variables:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-frontmcp-server", "--stdio"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb",
        "API_KEY": "sk-xxxxx",
        "LOG_LEVEL": "warn"
      }
    }
  }
}

Using the `serve` Subcommand

The --stdio flag also works with the serve subcommand:

{
  "mcpServers": {
    "my-server": {
      "command": "my-server",
      "args": ["serve", "--stdio"]
    }
  }
}

The --stdio flag is detected early, before any CLI framework initialization. Both my-server --stdio and my-server serve --stdio work identically.

Development with AI Coding Agents

When building a FrontMCP server with an AI coding agent (Claude Code, Cursor, Windsurf, etc.), use HTTP transport with frontmcp dev for the best experience. The dev server watches your source files and auto-reloads on every change — your agent edits code, the server restarts instantly, and the MCP client reconnects automatically.

This is the recommended workflow for “vibe coding” with FrontMCP. The agent has live access to the tools it’s building — it can edit code, test the result immediately, and iterate without any manual restart.

Step 1: Start the Dev Server

npm run dev
# or: frontmcp dev
# or: frontmcp dev -e src/main.ts

This starts two parallel processes:

tsx --watch — runs your server and auto-reloads on file changes
tsc --watch — async type-checker running in the background

The server URL is printed on startup (default: http://localhost:3000).

Step 2: Register as HTTP in Your MCP Client

Add your dev server to .mcp.json so the coding agent can use it while building:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Step 3: Code and Iterate

The workflow is now fully live:

Agent edits a tool, resource, or prompt in src/
tsx --watch detects the change and restarts the server (~200ms)
MCP client reconnects and sees the updated capabilities
Agent tests the change by calling the tool directly
Repeat — no manual restart needed

Stdio bridge: `frontmcp dev --stdio` (issue #399)

When a client must speak stdio (Claude Code’s stdio mode, MCPB-installed bundles, etc.) and you still want the dev hot-reload loop, run the bridge:

frontmcp dev --stdio
# or, with bridge-spawns-child-in-stdio (no HTTP loopback at all):
frontmcp dev --stdio --serve

Wire your client at the bridge — no mcp-remote needed:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "frontmcp", "dev", "--stdio"]
    }
  }
}

What the bridge guarantees:

Stdout is 100% JSON-RPC frames. Every diagnostic goes to ./.frontmcp/dev.log (override with --log-file <path>).
The session id survives reload. The bridge pins a uuid via FRONTMCP_DEV_FORCE_SESSION_ID; the child re-uses it on every restart so in-flight session state (auth, subscriptions) carries over.
Buffered RPCs during reload drain in FIFO order when the new child reports ready (sentinel __FRONTMCP_BOOTSTRAP_COMPLETE__ on stderr, or TCP probe in HTTP mode).
Structured errors instead of hangs. When the reload exceeds --reload-deadline-ms (default 30 000) or the buffer exceeds --buffer-size (default 8), the bridge synthesises dev_server_unreachable / dev_buffer_full / dev_reload_deadline (codes -32099 / -32098 / -32097) so the client spinner clears immediately.

Flags:

Flag	Default	Description
`--stdio`	off	Enable bridge mode.
`--serve`	off	Use stdio-over-pipe to the child (skips HTTP loopback).
`--log-file <path>`	`./.frontmcp/dev.log`	Bridge log destination.
`--buffer-size <n>`	8	Max RPCs buffered during reload.
`--reload-deadline-ms <ms>`	30000	Bound on how long the bridge waits for the child.
`-p, --port <port>`	3000	HTTP-mode loopback port. Ignored with `--serve`.

Why HTTP (Not Stdio) for Development

Aspect	HTTP + `frontmcp dev`	Stdio
Hot reload	Server restarts on file change, client reconnects	Must restart the entire process
Multiple clients	Agent + Inspector + you can all connect simultaneously	One client per process
Debugging	Logs visible in terminal, Inspector UI available	Logs mixed with protocol
Persistence	Server stays running across edits	New process per connection

Run npm run inspect in a separate terminal to launch the MCP Inspector alongside your dev server. This gives you a visual UI to test tools while your agent codes.

HTTP Transport

Connect to a FrontMCP server running as an HTTP server. Use this for remote deployments, cloud servers, or when you need the server to persist independently.

Local Development

Start your server, then point the client at it:

# Start the server
my-server serve -p 3005

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "http://localhost:3005/mcp"
    }
  }
}

Production Deployment

For servers deployed to a public URL:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://my-server.example.com/mcp"
    }
  }
}

With Authentication Headers

For servers that require authentication:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://my-server.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

Background Daemon on Port

Run your server as a background daemon on a TCP port:

# Start daemon on port 4000
my-server daemon start -p 4000

# Check status
my-server daemon status
# → Running (PID: 12345, started: 2025-01-01T00:00:00.000Z, port: 4000)

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "http://localhost:4000/mcp"
    }
  }
}

Unix Socket Transport

Connect via Unix socket for the lowest-latency local connections. The server runs as a background daemon.

# Start the daemon (creates socket at ~/.frontmcp/sockets/my-server.sock)
my-server daemon start

# Check status
my-server daemon status
# → Running (PID: 12345, started: 2025-01-01T00:00:00.000Z, socket: active)

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "http://localhost/mcp",
      "socketPath": "/Users/you/.frontmcp/sockets/my-server.sock"
    }
  }
}

The url field is required even for Unix sockets — the hostname is ignored, but the path (/mcp) is used for HTTP routing.

Publishing to npm

Make your FrontMCP server installable via npx:

1. Build the CLI Bundle

frontmcp build --target cli --js

2. Configure package.json

{
  "name": "my-frontmcp-server",
  "version": "1.0.0",
  "bin": {
    "my-frontmcp-server": "./dist/my-frontmcp-server-cli.bundle.js"
  },
  "files": ["dist/"],
  "dependencies": {
    "@frontmcp/sdk": "^1.0.0"
  }
}

3. Publish

npm publish

Users can then use your server with:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-frontmcp-server", "--stdio"]
    }
  }
}

Transport Comparison

Aspect	Stdio	HTTP	Unix Socket
Startup	Per-connection (~1s)	Persistent server	Persistent daemon
Latency	Lowest (in-process)	Network overhead	Very low (local)
Auth	Via env vars	Via headers/tokens	Via socket permissions
Persistence	None (ephemeral)	Full (sessions, SSE)	Full (sessions, SSE)
Multi-client	One client per process	Multiple concurrent	Multiple concurrent
Best for	npm packages, tools	Cloud, remote access	Local daemons, IDEs

Client Configuration File Locations

Client	Config File	Location
Claude Code	`.mcp.json`	Project root (per-project) or `~/.claude/.mcp.json` (global)
Claude Desktop	`claude_desktop_config.json`	`~/Library/Application Support/Claude/` (macOS)
Cursor	`.cursor/mcp.json`	Project root
VS Code	`.vscode/mcp.json`	Project root
Windsurf	`~/.codeium/windsurf/mcp_config.json`	Home directory

One-shot install for Claude Code (`<bin> install -p claude`)

Every server built with frontmcp build --target cli inherits an install subcommand that emits a full Claude Code plugin — MCP server entry, slash commands, and @Skill-decorated skills — in one step. End users don’t need to hand-edit .mcp.json or place SKILL.md files manually:

# As an end user, after installing your server (e.g. via npm install -g):
my-server install -p claude          # writes ./.claude/plugins/my-server/
my-server install -p claude --scope user  # writes ~/.claude/plugins/my-server/
my-server install -p claude -p codex      # also writes the Codex mcp_servers entry
my-server install --status                # report what's installed per provider
my-server uninstall -p claude             # remove the Claude plugin tree

Selective installs are supported via --no-skills, --no-commands, and --only-mcp (just register the MCP server, skip the plugin folder). --dry-run prints the file plan without writing. Compared to the manual .mcp.json flow above, the plugin install also:

composes proper SKILL.md frontmatter from each @Skill’s decorator metadata (name, description, tags, license) so Claude Code’s filesystem loader can index the skill;
copies bundled references/, examples/, scripts/, assets/ resource directories alongside each SKILL.md;
writes a .claude-plugin/plugin.json manifest that registers the MCP server, slash commands, and skill list in one file;
tracks framework-managed files via the manifest’s managedFiles array so re-running install is idempotent and user-added files are never deleted on uninstall.

For the dev-tool equivalent (frontmcp plugin install --claude from a project root) and the full flag reference, see the CLI Reference.

Troubleshooting

Problem	Cause	Solution
Client shows “connection failed” with stdio	Server crashing on startup	Check `~/.frontmcp/logs/` for error logs
Garbled output in stdio mode	Log output on stdout	Ensure you’re using `--stdio` flag (auto-redirects logs)
“ENOENT” error for binary	Binary not in PATH	Use absolute path in `command` field
”ECONNREFUSED” for HTTP	Server not running	Start with `my-server serve -p PORT` first
Socket file not found	Daemon not started	Run `my-server daemon start` first
Permission denied on socket	Socket owned by another user	Check file permissions: `ls -la ~/.frontmcp/sockets/`
npx hangs on first run	Package not cached	First run downloads the package; subsequent runs are fast

​Quick Reference

​Stdio Transport

​Using npx (npm package)

​Using a Local Binary

​Using Node.js Directly

​With Environment Variables

​Using the serve Subcommand

​Development with AI Coding Agents

​Step 1: Start the Dev Server

​Step 2: Register as HTTP in Your MCP Client

​Step 3: Code and Iterate

​Stdio bridge: frontmcp dev --stdio (issue #399)

​Why HTTP (Not Stdio) for Development

​HTTP Transport

​Local Development

​Production Deployment

​With Authentication Headers

​Background Daemon on Port

​Unix Socket Transport

​Publishing to npm

​1. Build the CLI Bundle

​2. Configure package.json

​3. Publish

​Transport Comparison

​Client Configuration File Locations

​One-shot install for Claude Code (<bin> install -p claude)

​Troubleshooting

Quick Reference

Stdio Transport

Using npx (npm package)

Using a Local Binary

Using Node.js Directly

With Environment Variables

Using the `serve` Subcommand

Development with AI Coding Agents

Step 1: Start the Dev Server

Step 2: Register as HTTP in Your MCP Client

Step 3: Code and Iterate

Stdio bridge: `frontmcp dev --stdio` (issue #399)

Why HTTP (Not Stdio) for Development

HTTP Transport

Local Development

Production Deployment

With Authentication Headers

Background Daemon on Port

Unix Socket Transport

Publishing to npm

1. Build the CLI Bundle

2. Configure package.json

3. Publish

Transport Comparison

Client Configuration File Locations

One-shot install for Claude Code (`<bin> install -p claude`)

Troubleshooting