Built by agents. Legible to agents.

The hosaka fleet is agent-built. Every interface — the MCP server, the API, the CLI, the sitemap, the .md mirrors — is designed to be consumed without a browser.

Connect an MCP client · Run the curl

hosaka music data — the MCP server

hosaka music data is a remote MCP server (Streamable HTTP) that gives agents verified facts about artists, releases, labels, tracks, gigs and hosaka’s discovery signals, with attribution on every response and honest gaps instead of guesses. It is also the ChatGPT connector “hosaka music data”. The connector is called ono-sendai; its documentation is vendored here from a pinned commit of that repository — connect → tools → envelope → errors and limits → data posture.

At a glance — every fact in these rows is quoted from the vendored docs, and a test keeps it that way

MCP endpoints	`/mcp` — core, the nine tools every client gets · `/mcp/full` — full, core plus the discovery tools
Hosts	`https://mcp-staging.hosaka.fm` — live on hosaka crate · `https://mcp.hosaka.fm` — provisioned (DNS, TLS, legal pages, OAuth discovery) but not yet promoted; the host table on Connect is the record
Discovery	/.well-known/oauth-protected-resource — RFC 9728 protected-resource metadata (the PRM): `resource`, `authorization_servers`, `scopes_supported`, `resource_documentation`
Sign-in	OAuth 2.1: authorization code with PKCE, `S256` only; client ID metadata documents (CIMD) preferred, dynamic client registration (DCR) as the fallback; the RFC 8707 resource indicator on both requests; scopes `openid email offline_access`
Anonymous use	Two tools work without an account: `resolve_artist` and `get_artist` (the summary card). Everything else needs a hosaka sign-in
Attribution	Every response carries `attribution.line`. Whatever you show a user from these tools must show that line

Connect — Endpoints, discovery, anonymous vs signed-in tools, OAuth 2.1, set-up for ChatGPT, Claude and any MCP client, host status.
Tools — Every tool with profile, auth, annotations, description and input schema — generated from the server’s own registry.
Envelope — The one response shape: ok and present, ambiguity states, untrusted text, attribution, next actions, meta, pagination, the token budget.
Errors and limits — Every error.type with recoverable/retryable, cursors, deadlines, the degraded window, visible budgets, replays.
Data posture — Attribution travels with the data; licences by facet; crate’s terms; what the server never returns.

Legal: privacy policy · terms of use · support — the connector’s own text, vendored the same way.

The crate API and the CLI

Below the connector sits the substrate it reads from: crate, hosaka’s public data API. Agents that do not speak MCP use it directly — keyless preview endpoint, crate-cli robot contract, SDK, machine-readable surfaces.

Why

hosaka is built by one operator with an AI-agent fleet — every tool in this document is a direct output of that practice.

Agent-legibility is a first-class constraint, not an afterthought. Stdout is data. Stderr is diagnostics. Exit codes are contracts. The keyless endpoint fails closed — 503 when the substrate is busy — so your agent handles it explicitly rather than silently swallowing an error page.

For the full data model behind what the API returns, see how hosaka knows.

30-second start

No API key. No sign-up. 100 req/hour/IP. CORS *. Fails closed on 503 (substrate busy) — handle it explicitly.

curl -sL 'https://crate.hosaka.fm/api/v2/preview/artist?q=four+tet'

Response keys: object · present · display · cluster_id (nullable — not all artists resolve to a Discogs or MB ID) · resolved_via · emergence_tier · arc[≤6] · arc_truncated · booked_with[≤3] · press_count · note · generated_at

cluster_id is nullable: artists without a Discogs or MusicBrainz anchor return null. Your code must handle that case — it is not an error.

crate-cli robot contract

Source: github.com/hosaka-fm/crate-cli — public repo, tagged release. There is no package registry entry; build it from source.

stdout = untransformed API JSON. stderr = diagnostics. These channels never mix. Pipe stdout to jq, redirect stderr to a log — they will never cross.

Exit code dictionary
Code	Meaning	Notes
0	ok	success — including honest-gap (present:false) bodies; never exit 1 for "no results"
1	usage error	bad args/flags; the error names the corrected invocation
2	auth error	missing/invalid API key (HTTP 401/402)
3	invalid input	the API rejected the input (HTTP 400); its hint is passed through
4	rate-limited	HTTP 429 — Retry-After surfaced on stderr; the CLI never auto-retries, the agent decides
5	server error	upstream server error (HTTP 5xx)
6	network error	DNS failure, timeout, connection refused
7	config error	config file unreadable or corrupt

crate robot-docs — paste-ready agent handbook for pasting into a system prompt. crate capabilities — machine contract JSON listing every available command and flag. crate triage — auth check + substrate health + suggested next commands. crate preview <name> — keyless single-artist query.

# Confirm auth and substrate health before a batch run
crate triage

# Pull the robot handbook into a system prompt
crate robot-docs

# Query without a key
crate preview 'four tet'

# Machine-readable capability list
crate capabilities

All four agent-oriented commands. stdout = JSON. stderr = human-readable diagnostics.

SDK

TypeScript SDK — generated types, every https://crate.hosaka.fm endpoint. Source: github.com/hosaka-fm/crate-sdk — public repo, tagged release. There is no package registry entry; build it from source.

SDK docs and generated types. For production access beyond the keyless tier, see hosaka for developers.

Machine-readable surfaces

This site publishes a set of machine-readable surfaces designed for agent consumption:

/llms.txt — site one-liner, page index, endpoint facts
/<page>.md — prose mirror for every route (same content, zero drift — generated from the same source module)
/sitemap.xml — canonical page list with real lastModified dates
OpenAPI spec via the SDK docs at crate-sdk.hosaka.fm

llms.txt is a convenience index for language models, not a ranking claim or SEO artefact.

Etiquette

Rate limit: 100 req/hour/IP on the keyless endpoint. Cached responses carry s-maxage=300 — respect it. Identify your bot via User-Agent (e.g. MyBot/1.0 (github.com/you/repo)).

If you need higher volume or a keyed tier, see hosaka for developers.