# How You Rank — bring your AI How You Rank records results for many kinds of games and computes many ranking views over the same match history. Everything a person can do here, their connected assistant can do too — and nothing a person cannot do becomes possible by connecting one. ## Connection Endpoint (MCP, HTTP POST): https://howyourank.com/mcp Discovery (RFC 9728): https://howyourank.com/.well-known/oauth-protected-resource/mcp Server version: 0.2.0 Tool catalogue: 16-tools Managed by the person at: https://howyourank.com/settings/ai Status: not open yet. Connecting will fail today, for these checked reasons: - Assistants cannot register themselves with the sign-in server yet. The sign-in server this endpoint names publishes no registration endpoint, so an assistant that has never connected here has no way to identify itself and the sign-in window never opens. It arrives with this site's production sign-in setup. Two steps in the connection belong to the person and cannot be automated: 1. Sign in to How You Rank in the browser window your assistant opens. 2. Read what the connection asks for, and click Allow. ## Authority Scopes are non-nested: holding one never implies another. Authority comes from the durable grant stored against the person, never from the scopes written into a token. Granted when the person signs in (3): - hyr:read — Read what you can already see Your assistant sees exactly what you see when you are signed in — never more, never another person's private data. * Games, variations and rulesets in the catalogue * Your groups, their members and their standings * Matches and sessions you can already open * Every ranking view, and the explanation of each method * Your collections, wishlists and homes - hyr:collection:write — Keep your shelf up to date Your own owned-games and wishlist rows — your lane alone, and every change is one you can undo. * Add and remove games you own * Add and remove wishlist games * Edit the items inside your own collections - hyr:result:write — Draft results for you to confirm Your assistant can write down a game night and hand it to you; nothing lands on anyone's standings until you tap confirm. * Draft a match or a whole game night, awaiting your confirmation * Suggest corrections to something already recorded * File a dispute, which asks a person to look — it changes no record Never granted by signing in — the person raises these themselves (2): - hyr:records:write — Record directly onto shared records Recording a match changes several people's ranking history at once, so signing in never grants this. You raise it yourself, once, and can lower it again. * Record matches and sessions without a confirmation step * Create groups, and add players to them * Link a player to an existing account found by exact email * Add and edit games and game notes in the catalogue - hyr:archive — Void and archive The reversible destructive verb, and only the reversible one. * Void a match * Delete a group Never issuable, on any tier, by any approval (5): - Bulk export your data Exports are a human action with a human's confirmation behind them. - Permanently delete anything Only reversible destruction is ever delegated. Permanent removal stays yours. - Create a user account An assistant may create guest players inside a group; it may never create an account for a person who has not signed up. - Create, read or revoke API keys Credentials are never handled by an assistant, on any tier. - Reach admin or operator queues These are withheld from your assistant because they are withheld from you. ## Tools - hyr_get_overview (hyr:read) — Where this person stands right now The orientation call — make it first. Returns who the person is on How You Rank, the groups they play in with each group's pinned ranking methods and their own position under them, any game night that is currently open, their most recent matches, and which permissions this connection actually holds. - hyr_find_games (hyr:read) — Search the game catalogue Find games by name or keyword. Returns slug, player counts, and how many variations each has. Use the slug with hyr_get_game. - hyr_get_game (hyr:read) — One game, in full Everything the encyclopedia holds about one game: how to play, history, official links and videos, its variations and their rulesets, frequently asked rules questions, scorecard styles, and which of the 49 ranking methods suit it. - hyr_describe_result_shape (hyr:read) — What a result for this game looks like Call this before hyr_record_match for any game you have not recorded before. Games differ enormously — some record points, some placements, some only a winner, some are co-operative — and this returns the exact result signature for a variation, naming the fields a match write must carry and the values they accept. - hyr_get_group (hyr:read) — One group: who plays, and how they are ranked A group's members, the ranking methods it has pinned as its scoreboard, its per-game weighting, and the standings under a method you choose. Groups this person cannot see are not returned. - hyr_get_rankings (hyr:read) — Standings under any of the 49 methods How You Rank's founding idea: the same match history, ranked many ways. Ask for a group's, a game's or a person's standings under a named method, or omit the method to get the list of methods with what each one measures. - hyr_list_matches (hyr:read) — Match history Recent matches this person can see, newest first, with each one's result and how it was recorded (by a person, or by an assistant, and which one). Filter by group or game. - hyr_get_match (hyr:read) — One match in detail Sides, players, scores, placements, which groups it counts in, whether anyone has disputed it, and its provenance. - hyr_list_sessions (hyr:read) — Game nights Sessions — an evening of games in one group. Returns what is open now and what has finished, with each night's games and standings. A match recorded while a night is open joins that night automatically. - hyr_get_collections (hyr:read) — The person's shelves Every collection they keep — a main shelf, a camping bag, a two-player shelf — plus their wishlist, with the games on each. - hyr_list_achievements (hyr:read) — What they have earned, and what is close The person's own achievements, and the ones they are nearest to earning. - hyr_get_connection (hyr:read) — What this connection is allowed to do This connection's own permissions: what it holds, what it does not, and what is never issuable to any assistant. If a write refuses for want of a permission, call this and tell the person exactly which one to raise, and where. - hyr_manage_collection (hyr:collection:write) — Keep the shelves up to date Add games to a collection, take them off, or move them between shelves. This is the person's own lane — nobody else's records change, and everything here is reversible. - hyr_file_dispute (hyr:result:write) — Ask a person to look at a match Files a dispute on a recorded match. This changes no record and no standings — it asks the people in the group to check something. Use it when you believe a result is wrong rather than editing anything. - hyr_record_match (hyr:records:write) — Record a match onto the group's records Writes a result. This is not the person's own lane: recording a match changes several people's ranking history at once, which is why signing in alone never grants it. Call hyr_describe_result_shape first unless you already know this game's result signature. If a game night is open in the group, the match joins it automatically. Every match you write is marked as recorded by this assistant. - hyr_manage_session (hyr:records:write) — Open or close a game night Starts, ends or reopens a session in a group. This matters beyond bookkeeping: while a night is open, every match recorded in that group joins it — by you, by the person, or by anyone else in the group. Generated from the connection contract. 16-tools.