Connect your first host — agent-connector docs

Guides

Connect your first host #

A host connection proves that a real agent host can launch your server, list its tools, call one tool, and surface errors. Do this in one host before trying to support every CLI agent-connector can target.

1. Pick one host and one scope #

Choose the host you use every day and one install scope, usually project scope while developing. Cross-host packaging comes later; the first goal is to remove uncertainty about paths, Node, working directory, and host approval UI.

2. Use the same launch shape everywhere #

Host settings differ, but the local stdio launch shape is stable: a server name, a command, and args. Start with an absolute server path so path resolution is not mixed into protocol debugging.

host-launch-flow.txt

text

One host settings file or UI
  -> server name: acme-db
  -> command: node
  -> args: [absolute path to my-mcp-server.mjs]
  -> host starts the process
  -> initialize handshake
  -> tools/list shows schema_summary
  -> one tools/call returns expected result

host MCP settings

json

{
  "mcpServers": {
    "acme-db": {
      "command": "node",
      "args": ["/absolute/path/to/acme-db-mcp/my-mcp-server.mjs"]
    }
  }
}

Windows path rule

In JSON config, prefer forward slashes in absolute Windows paths, or escape backslashes. D:/work/acme-db-mcp/my-mcp-server.mjs is less error-prone than an unescaped D:\work\... string.

windows-host-settings.json

json

{
  "mcpServers": {
    "acme-db": {
      "command": "node",
      "args": ["D:/work/acme-db-mcp/my-mcp-server.mjs"]
    }
  }
}

3. Verify the host, not the package #

Host check	What it proves
Server appears	The host parsed your config and can spawn the command.
Tool appears	Initialize and `tools/list` completed successfully.
One call works	The host can send `tools/call`, receive the result, and feed it back into the conversation.
Host restart still works	The config is durable and does not depend on your current terminal session.

4. Isolate failures by boundary #

Symptom	Likely boundary	First fix
Host cannot find server	Config path or command	Use an absolute path and verify `node` resolves outside your dev shell.
Server starts, no tools	Handshake or tool metadata	Re-test with Inspector and check stderr for import errors.
Call crashes	Handler validation	Send the smallest valid JSON input, then test invalid input.
Random protocol errors	stdio contamination	Move logs to stderr or a file; stdout belongs to JSON-RPC.

5. Let agent-connector take over later #

Once one host can call one tool, agent-connector can own repeatable rendering: server registration, install/doctor checks, optional hooks, statusline, actions, commands, skills, subagents, memory, and telemetry. Continue with Add your first connector surfaces.