Skip to content
kōan
Contents

Start

Server

Library

Playback

Automation

Reference

Protocol

MCP integration

kōan exposes two tools over the Model Context Protocol. The client reads the GraphQL schema, then drives everything through the graphql tool. There are two ways to connect:

Connecting to a server

The web UI's Assistants page has the address to copy and these steps; opening /mcp in a browser goes there too. The apps show the same address under Settings → Integrations → Assistants, with a link to that page; the server lists the koanMcp extension, and /rest/koanMcp gives the address, only once server.url is set. In Claude, open Settings → Connectors → Add custom connector, and enter https://<your server>/mcp. Claude opens the server's sign-in page; sign in with your kōan account and approve. Any MCP client that supports OAuth connects the same way.

The server is its own OAuth authorization server, so nothing else is needed in front of it, but it must know the address it is reached at: set server.url (e.g. https://music.example.com). Without it the server offers no sign-in, since an address taken from request headers could be chosen by whoever sends them. A server under a path needs one more route through its proxy for clients to find the sign-in; see Under a path.

What a connection can do:

[mcp]
redirect_hosts = ["claude.ai", "claude.com"]

A connection lasts as long as its refresh token is used within graphql.refresh_token_ttl (30 days by default). To end every connection at once, rotate the server's keys with koan auth regenerate-keys; clients then register and sign in again. Resetting an account's password ends that account's.

Running locally (stdio)

Run koan scan at least once so the library is indexed, then add kōan to Claude Desktop's config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "koan": {
      "command": "koan",
      "args": ["mcp"]
    }
  }
}

Claude Desktop does not read your shell's PATH, so a koan installed by Homebrew or mise needs its full path (which koan):

{
  "mcpServers": {
    "koan": {
      "command": "/opt/homebrew/bin/koan",
      "args": ["mcp"]
    }
  }
}

Restart Claude Desktop to pick it up.

Playing on a phone

Connected to a server, the assistant can play music on the koan apps linked to it rather than on the server: it lists them with clients, builds a track list with the library queries, and calls playOnClient. Ask for "something chill like Polar Bear on my phone" and the queue starts on the iPhone. See Playing on a linked app.

Tools

Tool Purpose
schema_sdl The GraphQL schema, so the model knows what it can ask
graphql Runs a query or mutation, in-process, against the same schema as the GraphQL API

Anything added to the GraphQL API is available over MCP without changes here. A request like "find my 90s electronic albums, pick one at random and queue it" becomes an albums query filtered by year and genre, then addToQueue and play.

koan mcp runs at user role, so it cannot trigger scans or change the output device unless KOAN_MCP_ADMIN=1 is set, and never moves files or rewrites config. See In-process access.