Quick start — agent-connector docs

Getting Started

Quick start #

The MCP developer deploying their own MCP everywhere — three steps: depend on agent-connector, declare your connector with defineConnector, then ship a branded CLI/package. During development you can still run the framework command from the project as a fallback.

Just want to see the usage of the CLIs you already use?

No defineConnector, no config file, no install. If you simply want to know how many tokens your agent hosts are burning, that is the agent user track — one connector-free command that reads their own session logs read-only.

Don't have an MCP server yet?

agent-connector deploys an MCP server you already have — it doesn't write one for you, so step 0 is having a server file. The official MCP SDK quickstart is the fastest on-ramp, and examples/acme-db/acme-db-mcp-server.mjs in this repo is a self-contained stub you can copy. Once you have a server file, point the connector's server at it (next step).

Add the dependency and create an agent-connector.config.{mjs,js,json} at your project root (found by walking up from the project dir, or pass --connector <path>):

terminal

bash

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

# 2. write agent-connector.config.mjs (defineConnector — see below)

# 3a. ship a branded CLI so YOUR users drive it (auto-scoped, no --connector):
acme-db detect            # list installed hosts + paradigms
acme-db audit             # catch package/bin/connector identity drift
acme-db install --dry-run # preview the diff
acme-db install           # write native configs everywhere
acme-db doctor            # verify — add --probe for a live MCP handshake (initialize → ping → tools/list)
acme-db upgrade           # day 2: re-render configs + heal the home-binary pointer (aliases: sync, update)
acme-db leaderboard       # acme-db's token footprint vs the boards
acme-db telemetry report --by tool   # which of acme-db's tools cost the most tokens
acme-db uninstall         # full inverse — removes everything install wrote (--purge, --dry-run work too)

# 3b. packaging/distribution artifacts are framework tooling:
npx @ken-jo/agent-connector package --connector ./agent-connector.config.mjs --format all --out ./dist

# 3c. development fallback only — run the framework from the project:
npx @ken-jo/agent-connector detect
npx @ken-jo/agent-connector install --dry-run

The config below is the canonical example — see defineConnector for the full field reference. Every command is idempotent, reversible, and --dry-run-able. install targets the hosts detected on your machine (or an explicit --targets list), intersected with the adapter registry. The server below points at a published package (command: "npx" + args: ["-y", "@acme/acme-db-mcp"]); while you're still developing, the same field can be command: "node" + a local server-file path (the acme-db-mcp-server.mjs stub above) — then switch to the npx-plus-package shape once you publish.

agent-connector.config.mjs

import { defineConnector } from "@ken-jo/agent-connector/sdk";

export default defineConnector({
  // package.json / npm metadata is the source of truth.
  // id/displayName/version are derived from name/mcpName/bin/version unless
  // you need a multi-instance alias such as "github-octocorp".
  // Host-native ids are generated during install; don't copy them back here.
  server: {
    transport: "stdio",
    command: "npx",
    args: ["-y", "@acme/acme-db-mcp"],
    env: { ACME_DB_DSN: "${env:ACME_DB_DSN}" },
    tools: { include: ["*"] },
    timeoutMs: 30_000,
  },
  hooks: {
    PreToolUse: {
      matcher: "acme_write",
      async handler(evt) {
        if (evt.toolName === "acme_write")
          return { decision: "ask", reason: "Confirm Acme DB write" };
        return { decision: "allow" };
      },
    },
    SessionStart: {
      async handler() {
        return {
          decision: "context",
          additionalContext: "Acme DB schema v12 is loaded.",
        };
      },
    },
  },
  telemetry: { enabled: true, modelFamilyHint: "auto", measureToolDefs: true },
  platforms: { warp: { hooks: false } }, // Warp is mcp-only: skip hooks
  targets: "auto",
});

Branded package first

Ship a branded CLI so your users run <your-tool> install / <your-tool> leaderboard (auto-scoped to your connector — see Embed it / branded CLI). Use npx @ken-jo/agent-connector … from the project only as a development fallback. Per-tool telemetry for your own wrapped server is automatic for stdio servers; remote servers are registered but not wrapped.

Quick start#

Quick start #