How agent-connector fits — agent-connector docs

Guides

How agent-connector fits #

agent-connector is not the MCP protocol and not a replacement for your MCP server. It starts after a plain MCP server works: it packages that server, renders host-native installs, and adds optional host surfaces such as hooks, commands, skills, subagents, memory, statusline, actions, and telemetry.

The boundary: MCP first, connector second #

A beginner should make one server work in one host before adding agent-connector. MCP proves the capability contract. agent-connector proves the distribution and host-integration contract.

Layer	Owns	Beginner question
`MCP server`	Tools, resources, prompts, argument validation, and application access.	Can one host call one useful capability?
`agent-connector`	Package identity, per-host config rendering, hook bridges, content surfaces, statusline/actions dispatch, doctor checks, and local telemetry.	Can the same package install cleanly across hosts?

The distribution layer #

defineConnector is the declaration that says, "this package exposes this MCP server and these optional host surfaces." From that declaration, adapters render the native shape each host expects instead of forcing every host into one invented config format.

connector-flow.txt

text

Plain MCP server works in one host
        |
        v
defineConnector({ server, optional surfaces })
        |
        v
agent-connector installer detects selected hosts
        |
        v
Per-host adapters render native config
  - MCP server registration
  - hook bridge where the host supports hooks
  - commands / skills / subagents / memory files
  - statusline / actions affordances where wired
        |
        v
doctor verifies the installed shape per host

What install actually does #

Resolve package identity. The package name, version, bin, and optional MCP metadata become the public connector identity.
Detect or target hosts. The installer works against detected hosts or the explicit --targets list, not every known platform blindly.
Render native files. MCP config, plugin manifests, command files, skill folders, rules files, and hook bridge entries are written in the host's own dialect.
Point runtime hooks at one home binary. Hook, statusline, action, and serve-wrapper dispatch go through the stable home binary so upgrades do not require rewriting every handler.
Verify with doctor. Installation is followed by host-specific checks that distinguish pass, warn, and fail states.

When not to add it yet #

Do not reach for agent-connector while the basic server contract is still unclear. If the tool name, schema, stdout behavior, result shape, or first host config is broken, fix MCP first. Add the connector layer when the next problem is distribution, cross-host parity, hooks, content surfaces, or telemetry for your package.