agent-connector

Deploy one MCP to every agent CLI.

Write your server + hooks once with defineConnector(), then install it into the native config — or package it as a real plugin — across every detected agent CLI (Claude Code, Codex, Cursor, Copilot, Gemini, OpenCode, Warp, Zed…).

Two audiences: connector developers start at Quick start; if you already run an agent CLI and just want token totals, jump straight to usage.

• Quick start — depend on the SDK, declare a connector, install it
• Ship it — direct install or a marketplace plugin
• What you define once — server, hooks, and the other surfaces
• How it works — single home binary, per-project data, hook paradigms
• CLI — every command at a glance
• Token telemetry & usage — per-tool telemetry vs. connector-free usage
• Publish to the MCP ecosystem — emit the official MCP standard artifacts
• Verification — how the platform coverage contract is proven

Quick start

agent-connector is an SDK connector developers depend on. Add it to the package that holds your connector, declare the connector once, then ship a branded MCP package/bin such as npx @acme/acme-db-mcp install — it deploys to every detected agent CLI in that host's own native config. Installing @ken-jo/agent-connector globally is not the branded MCP lifecycle path; reserve the global CLI guidance for connector-free token usage reports. Framework artifact tooling stays developer-facing and normally runs through npx @ken-jo/agent-connector ... --connector. The linear path is: get a server → declare it → install through your branded package.

0. You need an MCP server file first. The config below points at ./my-mcp-server.mjs, so that file must exist before you install. Don't have an MCP server yet? Copy examples/acme-db/acme-db-mcp-server.mjs (a self-contained ~35-line stub) as ./my-mcp-server.mjs, or follow the official MCP SDK quickstart.

# 1. add agent-connector as a DEPENDENCY of your connector package
npm install @ken-jo/agent-connector

// 2. package.json — this is the user-facing package identity
{
  "name": "@acme/acme-db-mcp",
  "mcpName": "io.github.acme/acme-db",
  "bin": { "acme-db": "./bin.mjs" },
  "dependencies": { "@ken-jo/agent-connector": "^0.4.94" }
}

// 3. agent-connector.config.mjs — declare your server + hooks once
import { fileURLToPath } from "node:url";
import { defineConnector } from "@ken-jo/agent-connector/sdk";

const serverPath = fileURLToPath(new URL("./my-mcp-server.mjs", import.meta.url));

export default defineConnector({
  // package.json / npm metadata is the source of truth. The host alias/runtime
  // id and connector version are derived from name/mcpName/bin/version unless
  // you need a legacy or multi-instance alias. Host-native ids are generated
  // during install, so do not copy them back into defineConnector({ id }).
  server: {
    transport: "stdio",
    command: "node",
    args: [serverPath],
  },
  // hooks, telemetry, and more surfaces — see "What you define once" below
});

The wiring contract is:

1. package.json defines the public product identity (name, mcpName, bin, version).
2. bin.mjs calls createConnectorCli({ packageJson, connector }) so every install/doctor/upgrade/uninstall command runs under the developer's brand.
3. agent-connector.config.* uses defineConnector({ server, ...surfaces }) to describe the real MCP launch shape or remote endpoint.
4. install renders that single declaration into each detected host's native MCP config. For stdio processes, the host points at the stable agent-connector home binary, which launches the real command and can measure per-tool traffic. For remote HTTP servers, the host receives the URL where supported; there is no stdio process to wrap.

Command boundary

Keep the two command layers separate:

| Layer | Who runs it | Examples | Purpose | | --- | --- | --- | --- | | Branded MCP lifecycle | Users of your MCP package | npx @acme/acme-db-mcp install, acme-db doctor --probe, acme-db upgrade, acme-db uninstall, acme-db telemetry report --by tool | Install, verify, update, remove, and inspect telemetry for your MCP. | | Framework tooling | MCP package developers | npx @ken-jo/agent-connector package --connector ./agent-connector.config.mjs | Emit host plugin bundles and MCP distribution artifacts from a connector config. | | Connector-free user telemetry | Agent-CLI users with no MCP package | npx @ken-jo/agent-connector usage report --by platform | Read host CLI logs read-only for whole-conversation token totals. |

If a command operates the MCP after it is authored, prefer the branded package/bin. If a command builds framework distribution artifacts, use the framework CLI.

MCP server launch examples

Pick the server shape that matches the MCP you are building. The wrapper package identity still comes from package.json; these examples only describe how to start or connect to the actual MCP server.

| Shape | Use when | Minimal launch | | --- | --- | --- | | Package-runner MCP | The MCP is published as a package. | npx -y @acme/acme-db-mcp | | Local server-process MCP | The MCP server ships inside your package. | node ./my-mcp-server.mjs | | Python MCP | The MCP server is Python and should resolve runtime deps at launch. | uv run --with mcp ./my_mcp_server.py | | CLI-based MCP | An existing executable exposes an MCP serving mode. | local-tools mcp serve | | Remote server MCP | The MCP is hosted behind an HTTP endpoint. | https://mcp.example.com/mcp |

Each snippet below is the server field for defineConnector({ ... }); only the local server-process example needs the serverPath helper shown inline.

Package-runner MCP — a published package that should be launched with npx:

server: {
  transport: "stdio",
  command: "npx",
  args: ["-y", "@acme/acme-db-mcp"],
}

Local server-process MCP — a bundled server file or binary:

import { fileURLToPath } from "node:url";

const serverPath = fileURLToPath(new URL("./my-mcp-server.mjs", import.meta.url));

server: {
  transport: "stdio",
  command: "node",
  args: [serverPath],
}

Python MCP — usually run through uv so dependencies are resolved with the server:

server: {
  transport: "stdio",
  command: "uv",
  args: ["run", "--with", "mcp", "./my_mcp_server.py"],
}

Use direct python ./my_mcp_server.py only when the runtime environment is already managed by your package or deployment wrapper.

CLI-based MCP — an existing executable exposes an MCP mode:

server: {
  transport: "stdio",
  command: "local-tools",
  args: ["mcp", "serve"],
}

Remote server MCP — a hosted MCP endpoint:

server: {
  transport: "http",
  url: "https://mcp.example.com/mcp",
}

# 4. deploy under your branded MCP package/bin
npx @acme/acme-db-mcp detect            # which platforms are installed here?
npx @acme/acme-db-mcp install --dry-run # preview every change first
npx @acme/acme-db-mcp install           # write native config in each host

install targets only the hosts actually detected on this machine (or an explicit --targets / connector.targets list), intersected with the current adapter registry shown on /coverage — there is no "install to every host unconditionally" path. @ken-jo/agent-connector is the framework dependency underneath; use it directly for framework packaging/debugging or connector-free token telemetry, not as the foreground install brand for your users.

Ship it: direct install or a marketplace plugin

Same one definition, your choice of distribution.

Direct install — your branded command (acme-db install, npx @acme/acme-db-mcp install) writes each host's native MCP + hook + content-surface config in place, with no per-platform marketplace submission or review. This is the Quick start path above.

Marketplace plugin — the framework package command turns the connector into a real plugin/extension bundle (manifest + bundled commands, agents, skills, hooks, MCP) from one definition. This is framework tooling, so run it with npx @ken-jo/agent-connector package --connector .... If you already keep the framework CLI installed globally, agent-connector package --connector ... is only the shorter equivalent. Hooks + MCP keep the telemetry serve-wrapper, so a marketplace-installed connector still reports per-tool tokens for its stdio server. --format all emits 10 host formats:

| Format | Hosts | |---|---| | claude-plugin | Claude Code · Codex · VS Code Copilot · OpenClaw · OMP | | codex-plugin | Codex (.codex-plugin/ manifest variant) | | copilot-plugin | GitHub Copilot CLI | | factory-plugin | Droid | | gemini-extension | Gemini CLI | | qwen-extension | Qwen Code | | agy-plugin | Antigravity (CLI + IDE) | | cursor-plugin | Cursor | | kimi-plugin | Kimi CLI | | npm-plugin | OpenCode · Kilo CLI · Pi |

Two official MCP standard artifacts are opt-in (they need a publish block, so they're excluded from --format all) — mcp-server-json (an MCP Registry server.json) and mcpb (a one-click MCPB bundle); see Publish to the MCP ecosystem.

# emit every host format (mcp-server-json + mcpb are opt-in by name)
npx @ken-jo/agent-connector package --connector ./agent-connector.config.mjs --format all --out ./dist-plugin
npx @ken-jo/agent-connector package --connector ./agent-connector.config.mjs --format gemini-extension --out ./ext   # or just one

# if you already keep the framework CLI globally installed, the same command is:
agent-connector package --connector ./agent-connector.config.mjs --format all --out ./dist-plugin

# e.g. Claude Code:  /plugin marketplace add ./dist-plugin/claude-plugin
#                    /plugin install <connector-id>@agent-connector
# e.g. Gemini CLI:   gemini extensions install ./dist-plugin/gemini-extension/<id>

Embedded-path caveat. Most host bundles bake in the absolute home-bin launcher path of the machine that ran package, so they're valid for a local install on that same machine/home. For shared distribution use npm-plugin or the MCP standard artifacts, or re-run package per machine.

Let your branded MCP package drive the host's own install flow with install --method marketplace:

acme-db install --method marketplace

# framework fallback for local framework development/debugging only
npx @ken-jo/agent-connector install --method marketplace --connector ./agent-connector.config.mjs

• What it does — stages the bundle, registers a local marketplace where the host has one, then runs the host's plugin-install verb (or, for npm-plugin hosts, writes a local file:// entry); headless and idempotent. Other marketplace-format hosts print the exact manual commands.
• Host coverage — live-verified for Claude Code, Codex, OpenCode, Kilo (CLI + ext), and Antigravity (CLI + IDE) on Linux, Windows, and macOS; Droid and Qwen Code have the driver shipped but pending a live host; Gemini CLI is legacy (sunsetting toward Antigravity — driver kept for existing installs).
• Safety + reversal — a guard refuses installing the same connector by BOTH methods, uninstall --method auto reverses whichever method is installed, and doctor checks registration drift.

Ship a branded CLI

A connector developer can ship their own bin instead of having users type agent-connector. createConnectorCli({ packageJson, connector }) (from the @ken-jo/agent-connector/cli export) derives the bin name/version from package.json and exposes every subcommand under your brand, fully delegated and auto-scoped to your connector — so your users do not need a framework global install or --connector for branded MCP install/doctor/uninstall. See examples/branded-cli for the full, runnable package.

#!/usr/bin/env node
// bin.mjs — every agent-connector subcommand, branded as `acme-db`
import { createConnectorCli } from "@ken-jo/agent-connector/cli";

// run() resolves to the exit code and never calls process.exit
process.exitCode = await createConnectorCli({
  // packageJson supplies public identity: name, mcpName, bin, version.
  packageJson: new URL("./package.json", import.meta.url),
  // connector supplies behavior: server, hooks, skills, telemetry.
  // These are two layers, not duplicate id/display-name inputs.
  connector: new URL("./agent-connector.config.mjs", import.meta.url),
}).run();

After a consumer installs your package, the acme-db bin is on their PATH and every command is scoped to your connector (acme-db install ≈ agent-connector install --connector ./agent-connector.config.mjs). Auto-scoping is pure argument injection over the SAME single home binary; serve and hook still route through the one ~/.agent-connector home binary every host config points back to. An explicit --connector / --connector-id always overrides the injected default.

What you define once

A single defineConnector({...}) declares your MCP server + lifecycle hooks, and optionally the additional surfaces — commands, skills, subagents, memory, statusline, actions, plus host-native escape hatches. agent-connector renders each surface into every detected host's native format, or skip-warns (never silently drops) where a host can't support it.

import { fileURLToPath } from "node:url";
import { defineConnector } from "@ken-jo/agent-connector/sdk";

// Resolve your server to an absolute path — host CLIs spawn it from their own CWD.
const serverPath = fileURLToPath(new URL("./my-mcp-server.mjs", import.meta.url));

export default defineConnector({
  server: {
    transport: "stdio",
    command: "node",           // or "npx", "python", etc. — whatever starts your server
    args: [serverPath],        // replace with your real server entrypoint
    env: { ACME_DB_DSN: "${env:ACME_DB_DSN}" },
  },
  hooks: {
    PreToolUse: {
      matcher: "acme_write",
      async handler(evt) {
        return evt.toolName === "acme_write"
          ? { decision: "ask", reason: "Confirm write" }
          : { decision: "allow" };
      },
    },
  },
  // telemetry is on by default
});

npx @acme/acme-db-mcp install turns that into, e.g.:

| Host | What gets written | |---|---| | Claude Code | ~/.claude.json → mcpServers.acme-db (+ hooks in ~/.claude/settings.json) | | Codex CLI | ~/.codex/config.toml → [mcp_servers.acme-db] (+ ~/.codex/hooks.json) | | Cursor | ~/.cursor/mcp.json → mcpServers.acme-db (+ ~/.cursor/hooks.json) |

…each pointing hooks at a single stable home binary, so one update propagates everywhere.

Secret env-refs (${env:VAR}). Write "${env:VAR}" (or "${env:VAR:-default}") anywhere in command / args / env / url / headers to reference an environment variable.

On hosts with native interpolation (Claude Code, Cursor, VS Code Copilot, amp, codebuff) the token is written through to the host config and resolved at runtime. Every other host has no native interpolation, so the value is resolved to a literal at install time; an unset variable with no default resolves to an empty string, and install emits a warn for it on a literal-resolving host.

Native hooks escape hatch. The normalized hooks API covers the 13 cross-platform events; for host-only events (Claude Code alone ships 30) declare platforms: { "claude-code": { nativeHooks: { TaskCompleted: { handler } } } }.

The handler receives the host's raw payload and whatever it returns is the verbatim JSON reply (exit 0 only — exit-2 blocking isn't modeled). Hosts supporting host-native passthrough: amp, claude-code, continue, copilot-cli, cursor, gemini-cli, hermes, jetbrains-copilot, kimi, nemoclaw, omp, openclaw, opencode, qwen-code. Others skip-warn.

Host-config key patches. For host-exclusive settings keys no other surface reaches, declare platforms: { "claude-code": { configPatch: [{ key, value, reason }] } } (Claude Code only for now; other hosts skip-warn with the exact manual edit).

Semantics are fixed: set-if-absent + skip-warn on any conflict — never overwrite, never deep-merge. Ownership is refcounted in a persisted ledger; security-relevant keys and keys agent-connector models as first-class surfaces are hard-refused.

Memory, statusline, actions, and the SDK

• memory (aligned with the AGENTS.md standard) — ship standing guidance into the memory/rules file each host actually reads. AGENTS.md adopters get the standard file; host-specific exceptions such as Claude Code → CLAUDE.md and Gemini CLI → GEMINI.md are wired per their own official docs. Writes are surgical marker-fenced, hash-stamped managed blocks — multiple connectors coexist, bytes outside your markers are never touched, and uninstall excises exactly your blocks.
• statusline (defineStatusline) — a live HUD render function the host calls on every status refresh. v1 registers Claude Code's settings.json.statusLine or Qwen Code's settings.json.ui.statusLine (set-if-absent, refcounted, reversible); other hosts skip-warn. The runtime is fail-safe: any error exits 0 with empty stdout so a HUD never wedges the host.
• actions (defineAction) — named, user-invocable operations dispatched by the universal verb agent-connector action <platform> <id> --connector <id>. install emits host-side affordances on droid, hermes, nemoclaw, omp, openclaw, and warp; other hosts skip-warn. Error semantics are user-triggered (unknown id or throw exits 1).
• The Connector SDK (@ken-jo/agent-connector/sdk, /sdk/test) — the consolidated authoring surface re-exports defineConnector, the full define* family (defineHook, defineCommand, defineSkill, defineSubagent, defineMemory, defineStatusline, defineAction, defineConfigPatch, defineNativeHook), introspection helpers (hostsSupporting, capabilitiesOf, surfaceSupport), and an offline harness (simulate, explain, explainHooks) that runs the real adapter parse→handler→format chain to answer "does my handler actually work on host X?" before you touch a real host. Agent-facing guidance is intentionally split into a small router skill plus focused references under skills/agent-connector/references. See docs/ARCHITECTURE.md.

How it works

• Home-dir, single binary. The runtime installs once under ~/.agent-connector (override AGENT_CONNECTOR_DATA_DIR). Every host config we write is a thin pointer back to that one binary. Updates are explicit/managed (agent-connector upgrade), never silent auto-update.
• Per-project data, kept. Telemetry/state is keyed by a stable project identity (git remote or normalized path), partitioned per project, stored under the home data-root — surviving git clean, shared across hosts opening the same project.
• Native config stays native. We never relocate a host's own settings files; only framework-owned state lives under the data-root.
• Windows-first correctness. No symlinks, no POSIX-only assumptions.

Three hook paradigms, all install-verified across the registered platform set (see /coverage and docs/ARCHITECTURE.md):

| Paradigm | Platforms | |---|---| | json-stdio (full hook dispatch) | CodeBuddy · Claude Code · Codex CLI · Cursor · VS Code Copilot · JetBrains Copilot · GitHub Copilot CLI · Gemini CLI · Qwen CLI · Kiro · Kimi CLI · Crush · Goose · Hermes · Droid (Factory) · OpenHands · Antigravity · Antigravity CLI · Continue · Amazon Q · Grok CLI · Devin CLI | | mcp-only (MCP registration only) | Warp · Roo Code · Cline · Trae · Zed · Codebuff · Mux · Pi · Windsurf · Open Interpreter · Junie · Mistral Vibe | | ts-plugin (generated bridge module) | OpenCode · MiMoCode · Kilo CLI · Kilo · OMP · NemoClaw · OpenClaw · Amp |

Adding a platform = one registry entry + one adapter.

CLI

| Command | Purpose | |---|---| | detect | List installed platforms, scopes, capabilities, hook paradigm. | | install [--scope …] [--targets …] [--method …] [--dry-run] [--force] | Render + write MCP + hooks + content surfaces across targets. | | uninstall [--targets …] [--purge] [--method …] | Full inverse — removes everything we wrote; --purge also clears framework state. | | upgrade [--channel …] | Re-render host config + heal stale pointers + refresh the home binary (alias: update, sync); never a silent self-update. | | doctor [--probe] [--explain] | Per-platform health checks with fixes; --probe runs a live MCP handshake, --explain prints the per-(host, event) hook honor matrix. | | status | Light install-state: which connectors are present on which hosts (always exits 0). | | package [--format <fmt>\|all] | Emit a host plugin bundle, or an OFFICIAL standard artifact: mcp-server-json (registry) · mcpb (one-click bundle). | | action <platform> <id> [--connector <id>] | Run a declared action from the shell. | | telemetry report [--by …] [--since …] [--connector <id>] | Per-tool token footprint of your connector's own wrapped server. Stdio servers only. | | telemetry export [--format …] [--connector <id>] | Raw aggregate records for your wrapped server. | | usage report\|export\|leaderboard [--by …] | No connector needed. Host-native whole-conversation token totals parsed read-only from each agent CLI's own logs. Does NOT break down by individual MCP or tool. | | leaderboard [--since …] [--connector <id>] [--scope …] | Three origin-labeled boards with different prerequisites (🔌 MCP/plugin · 🛰️ host-native turns · 🖥️ host/user); counts are never summed across them. |

hook and serve also exist — internal entrypoints the written host configs point at; you never run them by hand. Full flag-level reference: the docs site /docs/dev/cli · llms-full.txt §3 (canonical, drift-guarded by tests).

Token telemetry & usage

Two independent, never-summed views of token cost:

• Per-tool telemetry for your own server (the MCP-developer path). No host reports per-tool usage back to an MCP server, so agent-connector measures your server's own bytes (args in, results out, tool schemas) and tokenizes them locally — aggregate counts only, stored locally, zero egress by default. Per-tool telemetry is automatic for stdio servers; remote (http/sse/ws) servers are registered but not wrapped (the proxy can't intercept remote transports). Read it with agent-connector telemetry report --by tool.

• Connector-free usage (agent-connector usage). Already run Claude Code / Codex / Cursor and just want totals? usage reads your local agent-CLI session logs read-only and never writes any host config — no connector, no install:

  npx @ken-jo/agent-connector usage report --by platform        # CLI/model/project/session/day
  npx @ken-jo/agent-connector usage leaderboard --by platform   # or --by model
  npx @ken-jo/agent-connector usage export --format csv --out usage.csv

  It reports whole-conversation totals per agent CLI / model / project / session / day. It does not itemize cost by individual MCP server or tool — agent CLIs don't log per-tool attribution.

Privacy & tokenizer. Default tokenizer is gpt-tokenizer (pure-JS, no native build) — o200k_base for OpenAI/Codex-family, a documented approximation for Anthropic; falls back to a chars/4 heuristic if it can't load. Every record carries a confidence tag. Raw tool arguments and results are never stored or transmitted. Off switch: AGENT_CONNECTOR_TELEMETRY=0, or telemetry: { enabled: false }.

Publish to the MCP ecosystem

Where the MCP standard already covers your server's functionality, agent-connector emits the standard exactly so your already-standard work is portable:

• package --format mcp-server-json → an official MCP Registry server.json (schema 2025-12-11). It describes your real upstream server (what a registry installer runs), not our telemetry wrapper. Publish it with the official mcp-publisher CLI.
• package --format mcpb → an official MCPB (.mcpb, formerly DXT) bundle manifest.json (manifest_version 0.3) for one-click local install in Claude Desktop and any MCPB host, with secrets routed through the host keychain (user_config).

Both read a publish block on your connector (the namespace you own + your published package + author):

defineConnector({
  server: { transport: "stdio", command: "npx", args: ["-y", "@acme/acme-db-mcp"] },
  publish: {
    registryNamespace: "io.github.acme", // a namespace YOU proved ownership of
    packageName: "@acme/acme-db-mcp",     // your REAL published package
    author: { name: "Acme Inc" },
  },
});

Config we write is the standard. install writes each host's native MCP config in the de-facto canonical mcpServers shape — { command, args, env } for stdio, { url, headers } for remote. The spec transport slug for streamable HTTP is streamable-http (registry server.json); host configs canonically use http. WebSocket (ws) is not an MCP spec transport and the standard artifacts reject it.

Forward-compatible by transport. The serve proxy is byte-transparent: it forwards every JSON-RPC message verbatim and only tees a copy to count tools/call round-trips. So newer MCP features ride through untouched — MCP Apps (the official io.modelcontextprotocol/ui extension) and any reverse-DNS extension negotiated at initialize. A connector whose server already speaks these deploys across every host and keeps its telemetry today, no agent-connector change required.

Verification

The full single-API contract is install-verified across the current platform registry by a committed registry-driven install-roundtrip harness that, for every adapter, drives the real install → uninstall into an isolated HOME and asserts on-disk placement + zero residue. A separate committed scripts/verify-host.mjs driver installs real host CLIs from the verification matrix and checks install → placement → clean-uninstall; live hook dispatch + telemetry are proven end-to-end where the host can run headlessly. IDE extensions / GUI editors with no headless CLI stay covered by the install-roundtrip harness.

Dogfood result: porting the real multi-host context-mode plugin to defineConnector collapsed ~20,322 lines of hand-maintained per-host code down to ~76 lines (a 99.63% reduction). See the reports under docs/research/ and CHANGELOG.md.

Development

npm install
npm run typecheck
npm run build
npm run dev -- detect     # run the CLI from source via tsx

# Tests: scope + single-fork (NOT bare `npm test` — it OOMs low-RAM machines).
npx vitest run --pool=forks --poolOptions.forks.singleFork=true --poolOptions.forks.maxForks=1 \
  tests/adapters/<host>.test.ts

Contributing

PRs welcome — especially new host adapters and fixes verified against a host's primary source. See CONTRIBUTING.md for the dev workflow, the single-fork test discipline, the verify-first rule for adapters, and the new-host checklist. Want a new agent CLI supported? Open a host adapter request.

Security reports: see SECURITY.md.

License

Apache-2.0 © 2026 KenJo