Connecting Agents

Harbor exposes two MCP tools — inspect and exec. That's the entire agent-facing API surface. No matter how many plugins your workspace has, the agent sees only two tools, keeping its context budget tiny.

The two-tool pattern

Everything else — workspace switching, plugin OAuth, tool search, function publishing — is reachable through code inside exec. The agent learns the patterns from the meta skills.

Where to point your agent

Cloud (production)

https://mcp.tryharbor.ai/mcp

OAuth 2.1 + PKCE via WorkOS AuthKit. Compliant clients auto-discover at /.well-known/oauth-protected-resource.

Self-host

Run Cliff on your machine. It speaks the same MCP protocol over stdio, against your local Harbor SDK runtime. See Open Source → Cliff.

Per-client configuration

Generic MCP client

Any client that supports streamable-HTTP + OAuth 2.1 PKCE:

POST https://mcp.tryharbor.ai/mcp
Authorization: Bearer <authkit-access-token>
Content-Type: application/json

Resource discovery at /.well-known/oauth-protected-resource (RFC 9728).

The first thing every agent should do

// Step 1: probe the runtime
const status = await inspect({ code: "return await hrbr.auth.status()" });

if (!status.loggedIn) {
  // Step 2: trigger OAuth — host opens the browser
  await inspect({ code: "return await hrbr.auth.start()" });
}

// Step 3: discover what's available
const sources = await inspect({ code: "return await hrbr.sources.list()" });

// Step 4: search for the tools the user actually wants
const tools = await inspect({
  code: `return await hrbr.tools.search("${userIntent}", { describe: true })`
});

// Step 5: invoke
await exec({
  code: `return await ${tools[0].namespace}.${tools[0].name}(${argsJson})`,
});

This is exactly what /.well-known/agent-skills/harbor/SKILL.md teaches.

Tool budget math

A workspace with 50 plugins and 10 tools each (= 500 tool definitions) would normally cost your agent hundreds of thousands of tokens just to load the tool descriptors. With Harbor's inspect + exec pattern, it costs ~600 tokens: two tool definitions, two short JSON schemas, done.

You discover tools mid-run via hrbr.tools.search, by name and description, only when you need them.