Getting Started

Embed it / ship a branded CLI#

agent-connector is an SDK a connector developer depends on. With createConnectorCli({ packageJson, connector }) you expose every agent-connector subcommand under your own brand — fully delegated and auto-scoped to the connector your package ships. packageJson supplies public identity; connector supplies behavior, so these are separate layers rather than duplicate prompts. Your users run <your-tool> install / <your-tool> leaderboard / <your-tool> telemetry without a framework global install or --connector for branded MCP install commands.

1. Depend on it + add a bin#

agent-connector is a normal dependency (not -g). Your package declares a bin; installing your package links that bin onto the user's PATH.

package.json
json
{
  "name": "@acme/acme-db-mcp",
  "version": "1.0.0",
  "description": "Acme DB MCP server with branded install support",
  "type": "module",
  "mcpName": "io.github.acme/acme-db",
  "bin": {
    "acme-db": "./bin.mjs"
  },
  "files": ["bin.mjs", "agent-connector.config.mjs"],
  "dependencies": {
    "@ken-jo/agent-connector": "^0.4.94"
  }
}

2. createConnectorCli in your bin#

Import createConnectorCli from the @ken-jo/agent-connector/cli export, point it at your shipped config, and .run() it. That is the whole bin — every command behavior still lives in agent-connector; this is pure brand + auto-scope.

bin.mjs
ts
#!/usr/bin/env node
// bin.mjs
import { createConnectorCli } from "@ken-jo/agent-connector/cli";

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()
  .then((code) => { process.exitCode = code; })
  .catch((err) => {
    process.stderr.write(`acme-db: fatal: ${err?.stack ?? err}\n`);
    process.exitCode = 1;
  });

3. Your users drive your brand#

After installing your package, the consumer runs your bin. Each subcommand targets your connector with no --connector:

terminal
bash
# the consumer installs YOUR package; the acme-db bin is linked.
# no framework global install is needed for branded MCP install commands.
npm install @acme/acme-db-mcp

# deploy the acme-db connector across every detected agent platform.
acme-db install                 # auto-scoped — no --connector needed
acme-db install --dry-run       # preview the plan, nothing written
acme-db upgrade                 # bring everything current (alias: sync, update)
acme-db doctor                  # health-check every platform for acme-db

# telemetry + leaderboards, scoped to the acme-db connector:
acme-db leaderboard             # the 🔌 MCP/plugin section shows acme-db
acme-db telemetry report --by tool   # acme-db's per-tool token footprint
acme-db telemetry leaderboard        # which acme-db tool costs the most

# every agent-connector subcommand is available, branded as acme-db:
acme-db --help

Auto-scoping & the shared home binary#

A branded subcommand is just the matching agent-connector command with your connector pre-injected — argument transformation only, no duplicated logic. Config-path commands (install, upgrade [+ sync/update aliases], doctor, status, uninstall, package) get your config path; leaderboard / telemetry get your connector id as a filter; serve / hook get the id for the runtime.

branded ≈ agent-connector
bash
# a branded command  ≈  the agent-connector command, connector pre-injected:
acme-db install        ≈  agent-connector install --connector ./agent-connector.config.mjs
acme-db leaderboard    ≈  agent-connector leaderboard --connector acme-db
acme-db telemetry report --by tool
                       ≈  agent-connector telemetry report --by tool --connector acme-db

# the consumer can still override the auto-scope explicitly when they need to —
# an explicit --connector / --connector-id always wins over the injected default.

One home binary underneath every brand

Branded CLIs are a thin scoping layer over the same single home binary: serve and hook still route through the one ~/.agent-connector runtime that <your-tool> install wires every host's native config back to. Two packages that each ship their own brand share that infrastructure — see the operating model.