Connecting to hosaka music data (MCP)

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. It is also the ChatGPT connector "hosaka music data". This page is for people wiring a client to it; the tool-by-tool reference is tools.md, the response shape is envelope.md, errors and limits are in errors-and-limits.md, and what the data may be used for is in data-posture.md.

Endpoints

Path	Profile	Who it is for
`/mcp`	core — the nine tools every client gets	ChatGPT, Claude and any MCP client
`/mcp/full`	full — core plus the discovery tools (`list_breakouts`, `list_ones_to_watch`, `get_aura`)	clients that want the preview discovery lists

Both paths speak MCP Streamable HTTP: POST carries JSON-RPC, the server answers with JSON or an SSE stream according to the client's Accept header. Session termination (DELETE) is not offered and answers 405. Every tool is read-only, idempotent and open-world; see the annotations in tools.md.

Host	Status (2026-10-07)
`https://mcp-staging.hosaka.fm`	live on hosaka crate. The anonymous tools work for anyone; its signed-in tools accept only tokens from hosaka's internal test issuer (there is no public sign-in on staging), so third-party OAuth integration is tested against production once it is promoted
`https://mcp.hosaka.fm`	provisioned (DNS, TLS, legal pages, OAuth discovery) but not yet promoted — it serves no live data until the first production release (0.7.0). This row is updated when that happens

Health: GET /healthz (process up) and GET /readyz (ready to serve). Legal pages: /legal/privacy, /legal/terms, /legal/support.

Discovery

/.well-known/oauth-protected-resource (GET) — RFC 9728 protected-resource metadata (PRM). The same document is served at /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-protected-resource/mcp/full for clients that derive the path from the MCP endpoint URL. Fields: resource (one audience for both profile paths), authorization_servers, scopes_supported, bearer_methods_supported: ["header"], resource_name, resource_documentation.
MCP resources, readable without signing in: hosaka://capabilities (tools, limits, auth method, error codes and whether each is retryable), hosaka://envelope-schema (the JSON Schema of every response), hosaka://dossier-manifest and hosaka://semantics-dictionary (what the facets mean and where they come from).

Anonymous and signed-in tools

Two tools work without an account: resolve_artist and get_artist (the summary card). Everything else — catalogue search, similar artists, tracks, gigs, label cards, the discovery lists, profile and usage — needs a hosaka sign-in. The per-tool auth column is generated from the server's own registry in tools.md.

Calling a signed-in tool anonymously is not an HTTP error: the tool returns an envelope with ok: false, error.type: "unauthorized" and a mcp/www_authenticate entry in the result _meta, so a client can start the sign-in from inside the conversation. Anonymous capacity is limited; when it is used up the tool answers anonymous_capacity_exhausted and the fix is to sign in.

OAuth 2.1

hosaka's authorization server is WorkOS AuthKit at https://auth.hosaka.fm (the authorization_servers entry in the PRM). The flow is standard MCP authorization:

Read the PRM, then the authorization server's metadata.
Register the client: client ID metadata documents (CIMD) are preferred — give your client's HTTPS metadata URL as client_id; dynamic client registration (DCR) is the fallback.
Authorization code with PKCE, S256 only. Send the RFC 8707 resource indicator resource=<the PRM resource value> on both the authorization and the token request; tokens are bound to that single audience and are refused elsewhere.
Scopes: openid email offline_access (offline_access gives a refresh token so the connector does not re-prompt).
Present the access token as Authorization: Bearer <access token> on every request. Only the header method is accepted.

An expired, wrong-audience or otherwise invalid token yields HTTP 401 with WWW-Authenticate: Bearer resource_metadata="<PRM URL>" on any request (anonymous tools included); follow it back to step 1. A missing token is not an HTTP error: anonymous tools run, and a signed-in tool returns the in-result unauthorized envelope described above. If the account store cannot confirm the account, or the issuer's key set cannot be fetched, the server answers 503 without a challenge — the token may be fine, retry later instead of re-authenticating. insufficient_scope is reserved in the error vocabulary and not issued today: every signed-in tool uses the same scopes.

Set-up

ChatGPT (connector / app). Settings → Connectors → add https://mcp.hosaka.fm/mcp (or the staging host while production is not promoted) → "Sign in with hosaka" opens AuthKit → the tools appear in the composer. Try it before signing in: resolving an artist and the summary card work anonymously.

Claude. Settings → Connectors → Add custom connector → URL https://mcp.hosaka.fm/mcp → Claude discovers the PRM and AuthKit, registers itself (CIMD/DCR) and offers the sign-in on first use of a signed-in tool.

Any MCP client. Point a Streamable HTTP transport at the endpoint; the repo's mcp.json is the one-line manifest:

{ "mcpServers": { "hosaka": { "type": "streamable-http", "url": "https://mcp.hosaka.fm/mcp" } } }

Then initialize, tools/list, and tools/call as usual. A first anonymous call:

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"resolve_artist","arguments":{"q":"Four Tet"}}}

Read structuredContent (the envelope) rather than the text block; pass the returned cluster_id as key to the other tools. Honest gaps (present: false) and name ambiguity (ambiguity.state other than none) are described in envelope.md.

Cursors are per account

search_catalog cursors are issued only to signed-in accounts and are bound to that account and to the exact query; an anonymous client never receives one, and a cursor shown to another account is refused (invalid_argument). See envelope.md → Pagination.

Attribution

Every response carries attribution.line. Whatever you show a user from these tools must show that line (hosaka plus the named sources). See data-posture.md.

Provenance

Vendored from ono-sendai docs/agents/connect.md at commit a447f2b on 2026-10-13. ono-sendai is the source of truth; this page is regenerated from the pinned commit and a test fails if the two disagree. The other pages in this set: connect, tools, envelope, errors and limits, data posture — and the agents landing.