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

_{Define once → ship it as your own branded CLI → users install via their host's native marketplace → one command drives every CLI. Regenerate this demo.}

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.98" }
}

// 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 audit             # catch package/bin/connector identity drift
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.

Framework fallback can also install a connector source directly when you are
testing distribution intake: github:owner/repo, npm:@scope/package@version,
or an archive: / direct .tgz source. Every fetched source is cached under
~/.agent-connector/sources/ and must contain agent-connector.config.*.

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.

Native interpolation vs. literal-at-install resolution

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 } } } }.

Raw-payload semantics and the ~14 passthrough hosts

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).

Set-if-absent + refcount + denylist semantics

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 [<source>] [--scope …] [--targets …] [--method …] [--dry-run] [--force]	Render + write MCP + hooks + content surfaces. <source> may be local, GitHub/git, npm:<package>[@version], or .tgz/archive:.
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).
audit [--strict]	Pre-install package identity lint: package name/version/bin, runtime dependency, connector id/version drift, and publish files coverage.
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 (useful on low-RAM machines).
npm run test:single -- 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