Use the OSD CLI

Not yet available

The Open Service Directory (OSD) CLI is not yet open source or publicly published. This guide describes how it works so you can evaluate the workflow. Installation instructions will follow its public release.

The OSD CLI gives assistants one interface to search support listings, check brand endorsement, and connect to support agents through MCP. It requires Node.js 22.19 or later.

The examples follow the fictional Example Air scenario in Discover support.

Search a registry

export OSD_REGISTRY_URL=https://registry.example/
osd search "Example Air cancelled flight rebooking" \
  --contract-version 0.3.0 \
  --filter type=application/mcp-server-card+json \
  --page-size 5

The CLI queries --target <url> if given, then OSD_REGISTRY_URL, and otherwise the default registry, https://directory.zendesk.com. It returns the registry’s candidates and leaves selection to the caller. Add --json for structured output.

Verify and select a candidate

Add --verify to check each result against the manifest published on its brand domain:

osd search "Example Air cancelled flight rebooking" \
  --contract-version 0.3.0 \
  --filter type=application/mcp-server-card+json \
  --verify --json

Each result gets a verification annotation. Its verdict is one of:

Verdict	Meaning
verified	The complete entry matches an entry in the brand’s published manifest
mismatch	The manifest has the same identifier, but the entry differs. Inspect diff
no_match	The manifest has no entry with the candidate’s identifier
unreachable	The manifest could not be retrieved. Inconclusive, inspect detail
malformed	The manifest could not be validated. Inconclusive, inspect detail
invalid	Invalid candidate data or a local setup error prevented the check

To check one candidate on its own, save its result object (not the whole response envelope) as candidate.json:

osd verify --candidate candidate.json --contract-version 0.3.0 --json

Select a verified candidate that fits the customer’s request. Verification confirms the brand published the entry. It does not choose the agent or authorize a support action.

Connect through MCP

Use the Server Card URL from the verified candidate. osd mcp connects and lists the agent’s tools:

osd mcp "https://support.airline.example/server-card.json" --json

If the agent requires authorization, an interactive run opens a browser to sign in and caches the credentials. --no-auth prevents a new sign-in but still uses cached credentials.

Tool names and arguments come from the agent’s tool schemas. If the agent offers a get_rebooking_options tool:

osd mcp "https://support.airline.example/server-card.json" \
  --call get_rebooking_options --args '{"destination":"Singapore"}'

osd mcp does not check endorsement itself, so verify the entry first. The support agent decides which operations it allows and enforces authentication and permissions. The assistant obtains any confirmation the customer’s instructions or its own policy require.

Use the CLI in scripts

Use --json, read diagnostics from stderr, and check exit statuses. A successful search --verify does not mean every candidate verified, and a completed osd mcp --call does not mean the tool succeeded: inspect each verdict and tool result.

Run osd --help, or add --help to a command, for all options.