Ten99.Aria.Mcp.Codecks 1.0.742

Ten99.Aria.Mcp.Codecks

A Model Context Protocol (MCP) server for Codecks, the project-management tool for game teams. It gives an MCP-capable agent a full project-management surface over a Codecks workspace: cards, decks, spaces, tags, milestones, runs, journeys, comments, attachments, and dependencies.

It talks to the current Codecks API (api.codecks.io) with a Bearer token. Codecks' API documentation is still thin in places, so parts of this server were built by observing the calls the Codecks web app makes, an approach the Codecks team themselves suggested. It is not an official Codecks product.

Status

Community-maintained and provided as-is, on a best-effort basis. It drives some endpoints that are not formally documented, so a Codecks change could break a tool between releases. Issues and pull requests are welcome; please don't treat it as a supported product with an SLA.

Install

Packaged as a .NET tool (aria-codecks-mcp) on NuGet, run over stdio via dnx. You need the .NET 10 SDK.

Register it with your MCP client. On macOS / Linux use dotnet dnx; on Windows the standalone dnx command ships on the PATH with the SDK, so you can set "command": "dnx" and drop the leading "dnx" arg.

{
  "mcpServers": {
    "codecks": {
      "command": "dotnet",
      "args": ["dnx", "Ten99.Aria.Mcp.Codecks", "--yes", "--", "--config", "/path/to/codecks.config.json"]
    }
  }
}

Command-line equivalents: macOS / Linux dotnet dnx Ten99.Aria.Mcp.Codecks --yes -- --config /path/to/codecks.config.json; Windows dnx Ten99.Aria.Mcp.Codecks --yes -- --config C:\path\to\codecks.config.json.

Authentication

Codecks issues API tokens in your workspace settings. Two kinds work:

• cdxat_… — an organisation token (recommended for an agent).
• cdxut_… — a personal token.

The token is sent as Authorization: Bearer <token>; the workspace slug is sent as the X-Account header.

Config file (recommended, supports multiple workspaces)

Pass --config <path> to a JSON file. DefaultOrg selects the active workspace at startup; org_switch changes it at runtime (see Multi-workspace below).

{
  "Codecks": {
    "DefaultOrg": "my-studio",
    "Orgs": [
      { "Key": "my-studio",  "Account": "my-studio",  "Token": "cdxat_…" },
      { "Key": "side-project", "Account": "side-project", "Token": "cdxat_…" }
    ]
  }
}

• Account is the workspace slug (sent as X-Account).
• Key is the friendly name you pass to org_switch.
• Keep real tokens out of source control; point --config at a file outside your repo.

Single workspace

For a single workspace you can skip the file and pass --token <cdxat_…> --account <slug> instead.

Tools

66 tools, grouped by domain. Reads return a trimmed shape with a top-level count; use the matching *_get_detail tool for full data.

Cards — card_search, card_get_detail, card_list_by_deck, card_create, card_update, card_delete Every card in a response carries a displayId (the Codecks UI code, e.g. $1i1) alongside the raw accountSeq. Every tool that takes a card id accepts any of three forms interchangeably - the card UUID, the human card number (accountSeq), or that displayId - resolving to the UUID internally; the leading $ marks a UI code, a bare number is the raw seq. So "look at card $1i1", "update card 1141", and passing a UUID all work without the caller knowing the encoding. card_create / card_update take tags (masterTags), milestone, run/sprint, due date, assignee, effort, and priority. card_create also takes parentId to create the card directly under a parent/hero card (the parent is validated before the card is created, so a bad parent never leaves an orphan; if the card is created but can't be parented, the result says so via parentWarning rather than failing). sprintId on card_update can only move a card to a different run; to take a card out of its run entirely, pass clearSprint: true (the two are mutually exclusive). The same pattern clears the other relations that otherwise read an omitted value as "leave unchanged": clearMilestone: true, clearDueDate: true, and clearAssignee: true unset the milestone, due date, and assignee respectively, each mutually exclusive with its set counterpart (milestoneId / dueDate / assigneeId). card_update with visibility: 'archived' archives a card (still browsable in the archive); card_delete removes it from the UI entirely (visibility: 'deleted') - harder to find than archived, but not a permanent purge, so the card stays retrievable by id. deleteFiles additionally purges its attachments. Every card-read tool also carries visionBoard - null, or {id, accountSeq, state, url} when the card has an attached Vision Board - so a thin card whose real content lives on a board isn't mistaken for under-scoped work. Likewise every card-read tool (card_search, card_list_by_deck, card_list_hand, card_get_detail) carries parentCard - the parent/hero card's UUID, or null when the card has no parent - so a card's place in the hierarchy is always visible and never has to be inferred from a missing field.

Vision boards — vision_board_list, vision_board_get A Vision Board is a visual canvas (UI flows, game loops, narrative/quest maps, reference/art boards) attached 1:1 to a card. These read board metadata and the https://{workspace}.codecks.io/vision/{accountSeq} link; vision_board_get accepts a UUID, the board number, or a /vision/N link. The board's canvas contents (nodes) are not available over the API - they ride a separate realtime websocket channel (binary, cookie auth) the token can't reach - so use the link to open a board in the UI.

Card hierarchy — card_add_child, card_remove_child Parenting is parent-centric: the parent (hero) card holds a childCards list. These attach/detach one or more children under a parent in a single read-modify-write call (existing children preserved). Every id - parent and children - accepts a UUID, the accountSeq number, or the $displayId.

Hand queue — card_add_to_hand, card_remove_from_hand, card_list_hand A user's "hand" is the set of cards drawn for them to work on. The add/remove tools change one or more cards on a specific user's hand, named by userId (from user_list) - the organisation token can manage any user's hand, not just its own; card ids accept a UUID, the accountSeq number, or the $displayId. card_list_hand reads a user's hand back, in hand order: it returns {count, hand:[{sortIndex, card}]} with each card in the trimmed shape (displayId, vision board, etc.). The hand's contents are the active queue entries (cards drawn but not yet done), ordered by sortIndex. A hand entry whose card lives in a project the token can't read comes back as {sortIndex, card:null}, so the count still reflects the true hand size.

Card workflow — card_block, card_unblock, card_request_review, card_resolve_review Block/review states are driven by resolvable threads; resolving a review can optionally mark the card done.

Dependencies — card_list_dependencies, card_add_dependency, card_remove_dependency Add or remove from either direction (blocks / blockedBy); a single call updates both cards.

Comments — comment_list, comment_add, comment_edit, comment_react, comment_close, comment_reopen

Attachments — attachment_add, attachment_list, attachment_delete Uploads go through Codecks' signed S3 flow.

Decks — deck_get_detail, deck_list_by_project, deck_create, deck_update, deck_delete, deck_set_cover, deck_list_stock_covers, deck_move

Spaces — space_create, space_update, space_reorder, space_delete

Tags — tag_list, tag_add, tag_update, tag_remove Project-level tag CRUD; apply tags to cards via masterTags on card_create / card_update.

Milestones — milestone_list, milestone_create, milestone_update, milestone_delete

Runs (sprints) — run_list, run_config_list (read)

Journeys (workflows) — journey_list_templates, journey_get_template, journey_clone_template, journey_add_item, journey_set_step_zones, journey_list_decks, journey_get_items, journey_apply

Projects — project_list, project_get_detail

Users — user_list, user_get_detail

Workspace / org — org_get_account_info, org_list, org_switch

Multi-workspace

With several Orgs configured, org_list shows them and org_switch changes the active one for subsequent calls. org_get_account_info reports the current workspace and account id.

Rate limiting

Codecks allows 40 requests per 5 seconds. The server throttles itself to stay within that limit, so bursts of tool calls wait rather than fail.

Built on

Ten99.Aria.Hosting.Mcp.Core (the stdio MCP host) and Ten99.Aria.Common (generic primitives).

License

MIT © 1099 Ventures Inc. See LICENSE.