Skip to main content

MCP server

The Taxonomy API hosts a Model Context Protocol server at /mcp (streamable HTTP), in the same process as the REST API and behind the same JWT auth and roles. It lets AI clients search and compare games, read the taxonomy, and propose tags that a person then reviews.

Connect​

curl -s localhost:8080/auth/login -H 'content-type: application/json' -d '{"username":"admin","password":"..."}'
claude mcp add --transport http taxonomy http://localhost:8080/mcp --header "Authorization: Bearer <token>"

The token is valid for 8 hours. The web app's Connectivity page shows the same instructions for Claude, Claude Code and Cursor.

Tools​

ToolRolePurpose
search_gamesanySearch and filter games; returns a page and the total
get_gameanyOne game with characteristics, paths, origin and confidence
list_game_facetsanyStudios, types and statuses with counts
recommend_similar_gamesanyTag-similar games with shared tags
compare_gamesanyWhy two games are (not) similar: shared tags with rarity, tags unique to each
get_taxonomy_treeanyWhole taxonomy as a flat list
find_characteristicsanyBy name, synonym or path suffix
get_dashboard_statsanyCatalogue size and tagging coverage
set_game_characteristicseditorReplace a game's tag set (ids or paths)
create_taxonomy_node, update_taxonomy_node, merge_taxonomy_nodeseditorTaxonomy edits through TaxonomyService
list_pending_tag_reviews, accept_tags, reject_tagseditorReview queue
propose_tagseditorSave web-researched suggestions as Inferred tags

search_games, get_game and recommend_similar_games return the JSON in the first content block plus one resource_link per distinct http(s) thumbnail, with a MIME type guessed from the extension, so clients can preview images.

Characteristics can be given as node ids or as paths such as Theme / Fantasy. McpSupport.ResolveCharacteristic matches by path suffix, then by name or synonym; an ambiguous name returns an error listing every candidate path.

Not exposed: user and AI provider management, document fetching, deletes, taxonomy import, tagging runs.

Prompt: tag_game​

The prompt lets a client AI with web search do the research while the server supplies only the taxonomy and stores the result.

Both routes, in-app and MCP, share the same rules text and the same saving code. The client name and model are self-reported and stored as ProposedBy with Channel = external.

Code​

src/Kaleido.Taxonomy.Api/Mcp/ReadTools.cs, EditTools.cs, TaggingPrompts.cs, McpSupport.cs. Tests: tests/Kaleido.Taxonomy.Tests/McpTests.cs.