@mcpforge-ai/cli

Connect an mcpforge-hosted MCP server (and its agent skill) into your AI clients in one command. (Published as @mcpforge-ai/cli; the installed command is mcpforge.)

npx @mcpforge-ai/cli connect acme/petstore

That reads the server's public connect descriptor, configures every AI client it detects on your machine, installs the generated Claude skill, and verifies the connection.

What it does

1. Resolves the server from <workspace>/<slug>, a server URL, or a connect.json URL.
2. Detects installed clients (or use --client) and writes each one's native config:
   • Claude Code, Codex, & VS Code via their own CLIs (claude mcp add, codex mcp add, code --add-mcp)
   • Cursor, Devin (formerly Windsurf), Zed, Cline via their config files (each dialect handled)
   • Claude Desktop via the mcp-remote stdio bridge (its config is stdio-only)
3. Handles auth with two distinct credentials: your mcpforge access token (--token / MCPFORGE_TOKEN) to READ a private (non-discoverable) server's connect info, and a bearer server's own secret (--bearer / MCPFORGE_BEARER / prompt) to authenticate its CALLS. OAuth 2.1 is handled natively in the client (claude mcp login for Claude Code). Codex takes the bearer by env-var reference, so the value never lands on a command line. A non-discoverable bearer server needs both.
4. Installs the skill into each skill-aware client's folder (~/.claude/skills/<name>/ for Claude, ~/.agents/skills/<name>/ for Codex), verifying the bundle's sha256 before writing anything. --bundle writes it as a Claude Code plugin that carries the server + skill as one versioned unit.
5. Verifies by running an initialize + tools/list handshake against the endpoint.

Usage

mcpforge connect <server> [options]
mcpforge remove  <server> [options]   (alias: rm)   Take the server back out of your clients.

  -c, --client <ids>   Comma-separated clients (default: auto-detect).
                       claude-code, codex, vscode, cursor, devin, zed, cline, claude-desktop
                       (windsurf is accepted as an alias for devin)
      --project        Write (or, for remove, delete) project-scoped config in the current directory
                       (default: user/global). Remove uses the same scope, so pass --project to remove
                       a project-scoped entry.
      --token <token>  Your mcpforge access token (PAT), to read a private (non-discoverable)
                       server's connect info (or set MCPFORGE_TOKEN).
      --bearer <token> A bearer server's own secret, to authenticate its calls (or set MCPFORGE_BEARER,
                       a per-server secret; else you are prompted). A non-discoverable bearer needs both.
      --domain <host>  Base domain for the "<workspace>/<slug>" shorthand (default: mcpforge.dev).
      --bundle         Install the skill as a plugin bundling the server + skill.
      --no-skill       Do not install the agent skill.
      --no-verify      Skip the post-config connection check.
      --force          Reset an existing entry: remove it first, so re-connecting a server already
                       configured in a command client (e.g. Claude Code) succeeds instead of erroring.
      --links          Also print Cursor / VS Code one-click install links.
      --dry-run        Show what would happen without writing anything.
  -y, --yes            Non-interactive; never prompt.

Security

• The connect descriptor is public for a discoverable server (a non-discoverable one needs your access token to read it); a bearer server's own token you supply is written only into your own client config, never into shareable links.
• The skill bundle is verified against a sha256 digest published in the descriptor before extraction, and extraction is guarded against path traversal (zip-slip).
• Config files are written 0600, merged non-destructively (your other servers are preserved).

Development

TypeScript, no runtime deps beyond fflate (verified unzip). Requires Node ≥ 20.

npm install
npm run typecheck
npm test          # vitest
npm run build     # tsc → dist/

MIT.