mcp/pkg/harness is the adapter between an MCP client catalog and Harness tool definitions. It keeps MCP wire values below the Harness boundary, derives model-facing names from a binding and raw tool name, and asks Harness to gate each invocation rather than treating discovery as authorization.

Adoption boundary

Create a harness.Binding with a name, client.Definition, scope, visibility selector, and required startup posture. NewManager validates the binding set and dependencies. Start connects and discovers servers; StartAdoption listens for loop and session changes; Adopter.Install replaces the selected loop’s external toolset with protocol-neutral definitions.

Identity and scope

ToolInvokeIdentity and ToolIdentity preserve binding and server identity while preventing raw server descriptions from entering durable fingerprints. AllLoops, Loops, and Named choose visibility. A required binding failure stops startup; an optional binding reports a typed failure and leaves the remaining bindings available. Duplicate model names are rejected rather than silently shadowed.

Reconfiguration

EnableBinding, DisableBinding, AddBinding, ReplaceBinding, and RemoveBinding are explicit operations. Reconfiguration updates status and publishes notices; disabling a binding withdraws its definitions from later loop builds but does not retroactively grant or cancel an already running call. Sampling and elicitation use host-provided policies, and every tool call still passes through the Harness gate.

Errors and limits

Use ErrAlreadyStarted, ErrAlreadyBound, ErrNotBound, ErrManagerClosed, StartupError, BindingFailure, and DuplicateModelNameError with errors.Is or errors.As. Limits cover tool names, schemas, message bodies, startup and retirement timeouts, elicitation, sampling, and event queues. The adapter cannot make a disabled, failed, or unauthorized server available by editing an MCP catalog entry.

Runnable proof

stage-16-mcp-adoption uses a child server with one lookup tool, starts a session-scoped binding visible to all loops, installs it, disables it, and verifies the source, definition count, model-facing tool name, and status. Run it with node scripts/docs/run-examples.mjs. See the pinned manager, adopter, and Harness external-tool runtime.