kodapa MCP Server

kodapa exposes 18 public tools on this MCP endpoint.

Tools

• search

  Hybrid search across artworks, artists, poems, and collections. Uses BM25 (Tantivy) + dense vector lanes (SigLIP for visuals, LAION CLAP for audio, 67-d metadata) fused via Reciprocal Rank Fusion. Returns ranked matches with `match_reason` and `contributing_lanes` per result. Set `explain=true` for per-lane rank breakdown. `mmr` opts in to MMR diversity reranking. `rerank=true` runs the top-100 candidates through a cross-encoder (BGE-Reranker-v2-m3) for a 10–20% NDCG@10 lift — adds ~100ms but is

• recommend_feed

  Personalized artwork recommendations using the inference engine's 3-head model (H1 visual session, H2 visual core, H3 emotional). Reads from the precomputed top-200 feed cache when the user is warm; cold-start falls back to recency. Use `offset` to walk through the precomputed list — response carries `next_offset` (null when exhausted). Pagination only works in the personalized path; the recency fallback returns a single page. Requires auth.

• recommend_poems

  Personalized poem recommendations ranked by H3 emotional cosine similarity. Cold-start falls back to recency. Use `offset` to walk past the first page; response carries `next_offset` (null when the candidate pool is exhausted).

• find_similar

  Find artworks similar to a seed artwork via HNSW vector search across PE-AV/DINOv3/SigLIP/MERT/MS-CLAP slots, with Tantivy-title backstop.

• get_artwork

  Fetch artwork metadata + ml_meta (Gemini-extracted themes, mood, archetypes, color narrative).

• bulk_get_artworks

  Batch-fetch up to 50 artworks in one MCP call. Returns the same shape as `get_artwork` per id, in the order requested. Missing ids surface as `{id, error: "not_found"}` entries (the call still returns success for the rest). Use this to expand a top-K from `search`/`find_similar`/`recommend_feed` without paying N round-trips.

• compose_collection

  Server-side curation: assemble a diverse `size`-piece collection around a theme. Runs the full 6-lane hybrid retrieval, applies artist-diversity (1 piece per artist when possible), and returns ordered hits with `match_reason` per piece. Optional `anchor_artwork_id` adds a `find_similar` lane that mixes in pieces neighbour-to-anchor (anchor itself is excluded from the result). When the caller is authed, results are personalized via the same H3 emotional re-rank `search` uses. Theme matches are SO

• get_poem

  Fetch poem text + ml_meta (themes, mood, archetypes, language, raw_description).

• taste_profile

  Return the authenticated user's taste profile derived from the H3 emotional head — top themes, moods, colors, styles, and a natural-language summary. The unique value-add of this MCP server: the LLM can reason about taste in concept-space rather than 4096-d vectors. Requires auth.

• like_artwork

  Like, save, favourite or collect an artwork (POST) — or undo that (unlike:true). THESE ARE ALL THE SAME SINGLE ACTION on Kodopa: there is no separate saved store, and the user's "Your Likes" collection IS the set of likes. Use this tool for any of those words; do not report that saving is unsupported. Updates the inference engine + triggers H1/H2/H3 recompute. Requires auth. May legitimately refuse: liking needs an active subscription, is capped at 300/hour, 404s on an unknown id, and spends the

• share_work

  Mint a shareable link to a work or profile and return its URL, so the person can send it on. `kind` is "artwork" or "profile"; `target_id` is the artwork id or the profile's username. Links expire after 7 days. This only CREATES the link — it does not post or send anything anywhere, so hand the URL back and let them share it. Requires auth. There is no share quota — never tell the person they have a share limit or a remaining count.

• list_displays

  List the caller's paired displays (TVs, web players) — id, name and type. Call this before control_display so you can name a real display instead of guessing. Returns an empty list when nothing is paired, which means the person has no screen to cast to, not that the call failed. Requires auth.

• control_display

  Control one of the caller's own PAIRED DISPLAYS (a TV or web player they set up) — this is casting, NOT control of the phone or app they are talking to you on, so never claim you paused or resumed their current playback. `action`: show_artwork (needs artwork_id), next, previous, refresh, blank (clears the screen). Get display_id from list_displays. Requires auth; controlling a display the caller does not own is refused.

• create_playlist

  Create a real playlist in the caller's library from a list of artwork ids, in the order given. `name` is what they will see; `artwork_ids` should be 3-7 ids drawn from search or recommendation results. Audio works are filed as music and everything else as visuals; the kind is inferred. Use this when someone asks you to make, build or save them a playlist or a sequence — not merely to describe one. Ids that don't resolve are skipped; if none resolve the call fails rather than creating an empty pl

• follow_artist

  Follow an artist (or unfollow with unfollow:true). Following adds their new work to the caller's Following feed. `artist_id` is the artist's user id (the `artist.id` field on an artwork, e.g. USR_...), NOT an artwork id. Requires auth. For a subscriber a follow spends Pia and may be refused for insufficient balance; a re-follow is idempotent and never double-spends.

• like_poem

  Like, save, favourite or collect a poem (POST) — or undo that (unlike:true). All the same single action; there is no separate saved store. Updates H3 emotional. Requires auth. May legitimately refuse for the same reasons as like_artwork — subscription, 300/hour cap, unknown id, or insufficient Pia — so relay the refusal rather than retrying.

• subscribe_to_taste_changes

  Register an outbound webhook that fires when the authenticated user's taste signal materially shifts. **Phase 1 (2026-05-07): registration only — events do not fire yet. Phase 2 wires the H3-cosine drift detector + retry/DLQ.** Args: `url` (https-only, ≤2048 chars), `secret` (16-128 chars; phase 2 signs requests with HMAC-SHA256), `event_types` (CSV of `taste_changed`, `feed_shifted`). Response: `{id, status: "registered"}`. Use `DELETE /api/v1/account/webhooks/{id}` (REST) to revoke. Requires a

• kybele_chat

  Talk to Kybele — Kodopa's consciousness-coach AI persona that uses the user's taste profile. Returns a redirect pointer to the streaming REST endpoint (Kybele's Kimi K2.5 backend takes 10-30s, longer than MCP's request/response budget without SSE). 3 messages/day quota.