How to connect AgileHero MCP with Codex

List every workspace and project the token's user can access, so the agent can resolve the project uid that most other tools require. Call this first whenever no project uid is known — never ask the user to paste one. Returns workspaces (uid, name, plan, your role) with their projects (uid, name, url). Pro-pillar tools (wiki, metrics) need the workspace's plan to be pro or trial.

The product's global full-text search (OpenSearch): cards, epics, wiki pages and projects, matching titles, descriptions, comments, checklist items and attachment filenames, relevance-ranked with a recency boost. Use this to find anything by content ("the card where we discussed the migration"); use search_cards only for title-substring lookups inside one project. Each result carries a type, an action-ready uid (cards feed get_card/update_card, epics get_epic, wiki_pages show_wiki_page, projects the project_id parameters), a deep-link url, and <mark>-highlighted snippets showing why it matched. Optionally scope with project_id or assigned_to_me. Paginate with page/per_page; total_count is the full match count.

Read one card in full: its AgileHero Markup description with block ids plus description_version (the two inputs preview_description_update / update_description take), list placement, epic, labels, assignees, reporter, type, estimation, due date, checklists, links, attachments, related cards and threaded comments. Takes the card uid alone — there is no project_id parameter. Card uids come from list_cards, search or search_cards.

Read one epic in full: its AgileHero Markup description with block ids plus description_version (the two inputs preview_description_update / update_description take), name, number, color, start/end dates, assignees, checklists, links, attachments, every card on it (uid, number, title and its list with category — null list = backlog — in board order, so this is the way to list all cards of an epic and see which are to do, in progress or done) and threaded comments. Takes the epic uid alone — there is no project_id parameter. Epic uids come from list_epics or search.

List a project's whole wiki tree in display order — every folder and page with its uid, name, type (page or folder) and parent_id — so the agent can resolve the page uid show_wiki_page takes and pick a parent_id for create_wiki_page. Requires a Pro or trial workspace.

Retrieve a wiki page as AgileHero Markup (AHM) with its document_version. Content is AHM, not markdown — block ids, <discussion> anchors, and <image/>/<attachment/> references are part of the document; read get_ahm_spec before editing. Edit via preview_wiki_page_update then update_wiki_page, using the block ids and document_version returned here. Requires a Pro or trial workspace.

The AgileHero Markup (AHM) v1.0 specification — the ONLY rich-text format AgileHero accepts (markdown and HTML are rejected). Read this ONCE before writing or editing any rich text (wiki pages, card/epic descriptions, comments): vocabulary, attributes, escaping rules, and a worked example. Same text on the web: https://agilehero.io/docs/mcp/agilehero-markup

Create a wiki page (optionally inside a folder) with AgileHero Markup (AHM) content. Content must be wrapped in <agile-hero-markup version="1.0"> — markdown and HTML are rejected; read get_ahm_spec first. Returns the new page's uid, url, document_version and content. Requires a Pro or trial workspace.

REQUIRED first step of every wiki page update: validates the operations and returns the server-computed consequences (blocks added/removed/changed, files that would be permanently deleted, team discussions that would lose their anchors, possible-markdown warnings) plus the preview_token that update_wiki_page requires. Nothing is modified. Operations are block-addressed (replace_block / insert_after / delete_block / move_block) with AHM content — read get_ahm_spec first, and get block ids + document_version from show_wiki_page. Review the consequences before saving: a listed file deletion or discussion unanchoring is only acceptable when the user asked for it. Requires a Pro or trial workspace.

Apply a previously previewed update to a wiki page. Requires the preview_token from preview_wiki_page_update for EXACTLY these operations and this document_version — saving without previewing is impossible by design. Every save creates a page version humans can revert in the app. Returns the updated page (AHM + new document_version) and the applied consequences. Requires a Pro or trial workspace.

REQUIRED first step of every card or epic description edit: validates the block operations and returns the server-computed consequences plus the preview_token that update_description requires. Nothing is modified. Content is AgileHero Markup (AHM, description surface: no tables, colors, alignment, discussions, or file attachments) — read get_ahm_spec first; block ids and document_version come from get_card / get_epic.

Apply a previously previewed description update to a card or epic. Requires the preview_token from preview_description_update for EXACTLY these operations and this document_version — saving without previewing is impossible by design. Returns the updated description (AHM + new document_version).

List the whiteboards of a project (uid, name, element count, url). Use get_whiteboard to read a board's elements. Requires a Pro or trial workspace.

Create an empty whiteboard on a project. Add content with create_whiteboard_elements. Requires a Pro or trial workspace.

Read a whiteboard as a compact text representation: board bounds plus one line per element — "<type> <uid> at <x>,<y> size <w>x<h> [color] [parent <frame-uid>] [linked <card|epic> <uid>] \"text\"", connectors as "connector <uid> <from> -> <to>". Element uids from here are the handles every whiteboard write tool takes. Requires a Pro or trial workspace.

Create up to 100 whiteboard elements in one transactional call (all-or-nothing, one realtime event). Native sizes, colors, and text placement are applied server-side — usually give just type + text (+ color). Omit x/y and elements are auto-arranged (grid by default; arrange: row|column|grid, origin_x/origin_y/gap to tune); give x/y for full control. Frames contain elements via parent_id (an existing frame uid) or parent_ref (the ref of a frame earlier in THIS call). Connectors bind elements by uid (source_id/target_id) or batch ref (source_ref/target_ref) — never coordinates; anchors are computed by the UI. Requires a Pro or trial workspace.

Draw a diagram (flowchart, process, dependency graph) on a whiteboard from a semantic graph — nodes, edges, optional groups, NO coordinates: the server does layered top-to-bottom layout with native sizes and returns the created element uids keyed by your node ids. Placed below existing board content. Transactional (all-or-nothing, one realtime event). Max 20 nodes — split bigger flows into two diagrams. Keep shapes plain (rectangle) unless the semantics demand one (diamond = decision, stadium = start/end, cylinder = data store). Edit the result with update_whiteboard_elements — the layout never runs again. Requires a Pro or trial workspace.

Update up to 100 whiteboard elements in one all-or-nothing call: move (x/y), resize, restack (z_index), retext, recolor, reparent (parent_id — a frame uid, or "" to detach), and connector arrow/path/label. Element uids come from get_whiteboard; element types cannot be changed. Only supplied fields change — unrelated properties are preserved. Requires a Pro or trial workspace.

Delete up to 100 whiteboard elements in one transactional call. Deleting a frame or mind-map node releases its children onto the board (they are NOT deleted — include their uids explicitly to delete them too). Connectors attached to deleted elements are not removed and will dangle. Element uids come from get_whiteboard. Requires a Pro or trial workspace.

Run deterministic quality checks on a whiteboard: text likely overflowing its element, visibly overlapping elements, connectors with unbound or dangling endpoints, colors outside the UI palette, off-grid positions, and elements whose parent was deleted. Advisory — findings are suggestions, not errors, and a board with findings may be exactly what the user wants. Use after drawing to sanity-check, fix at most once, and do not loop chasing an empty report. Requires a Pro or trial workspace.

Convert a whiteboard element into a backlog item: a sticky note into a card or an epic, or a frame into an epic (the frame's sticky-note children become cards on that epic; already-converted children are re-assigned, not duplicated). The element stays on the board, linked to what it became — get_whiteboard shows the link. An element can only be converted once. The note/frame text becomes the title unless you pass one. Requires a Pro or trial workspace.

Convert a mind map into backlog items with a per-node mapping: the root can become a new epic (role "epic") or attach to an existing one (role "existing_epic" + target_epic_id); other nodes become cards on that epic (role "card") or project labels (role "label" — label nodes above a card node in the tree are applied to that card); role "skip" ignores a node. Pass the ROOT element uid as id and every node you want converted in nodes (unlisted nodes are ignored). One conversion per node: already-converted nodes are rejected up front — resubmit without them. Requires a Pro or trial workspace.

List a project's retrospectives: new-model retrospectives and health checks where the workspace has them, classic retrospective boards otherwise. A new-model entry has uid, name, kind (retro | health_check), status (open | live | closed), date (starts_on; closes_on for a health check), current stage, template, facilitator uid, counts of the actions it created, and url; the response adds the project's open_actions_count. Use get_retrospective for the full picture. Requires a Pro or trial workspace.

Create a retrospective: a new-model retrospective where the workspace has them, a classic retrospective board otherwise; the response is the retrospective as get_retrospective returns it (columns with their uids), so add_retro_items can follow immediately. A new-model retrospective comes from a template (default went_well), is open for notes at once and has you as facilitator; optional: focus, anonymity (default: the template's), participant_ids (a Selected-members retro; omit for every project member with write access), the check_in and feedback question kinds, and votes. The facilitator starts it and runs its stages in the app. Classic boards take name, date and previous_retrospective_id only and refuse the new-model arguments. Requires a Pro or trial workspace.

Read a retrospective as you may see it: a new-model retrospective or health check where the workspace has them, a classic retrospective board otherwise. A new-model retrospective returns setup, stages (current one, timer, progress), columns (with uids) holding topics (groups of notes, with uids), check-in and feedback tallies, your votes left, the Discuss queue and parked topics, proposals, actions (those it created plus the project's open ones) and, once closed, its summary. Privacy follows the room: before the reveal you get your own notes only (each column counts everyone's), authors only on named notes, vote totals only once the votes are revealed. A health check returns its dimensions and participation, your own ratings while open, and per-dimension aggregates once closed. Requires a Pro or trial workspace.

Add items to a retrospective as yourself, several at once: notes on a new-model retrospective where the workspace has them, cards on a classic retrospective board otherwise. Each item is { column, text, recipient_id? }: column is a column title (case-insensitive) or uid from get_retrospective; text is up to 1000 characters (255 on classic boards); recipient_id, the user uid of the teammate thanked, is required in a new-model kudos column and refused on classic boards. A new-model note starts its own topic and others see it once notes are revealed; notes are taken only while the retrospective is open for notes or in the Write stage, otherwise the call is refused with code wrong_stage and the current stage. PARTIAL failure: valid items are added, invalid ones are reported per index — check the "failed" array. Requires a Pro or trial workspace.

Move a retrospective item: regroup a note on a new-model retrospective where the workspace has them, move a card to another column of a classic retrospective board otherwise. New model, Group stage only: topic_id puts the note into that topic (group of notes); column (title or uid) makes it a topic of its own there, at position among the column's topics (omit for last). Pass expected_updated_at, the note's topic updated_at from get_retrospective, to be refused with code stale when someone regrouped it meanwhile. Outside Group the call is refused with code wrong_stage and the current stage; kudos and other notes never mix. Classic boards take column and position only (position omitted = top). Requires a Pro or trial workspace.

List the members of a project — every workspace member for a standard project; the creator, the workspace owners and admins, and anyone explicitly added for a private one — so the agent can resolve assignee uids instead of guessing names. Returns each member's uid, full name, email and workspace role (owner, admin, member or observer). Those uids are what assigned_to takes on create_card, update_card, create_epic, update_epic and create_roadmap_slot.

List the lists of a project's kanban board so the agent can resolve a valid move_card destination. Returns each active list in display order with its uid (usable as a move_card target) and display name. The backlog is included as a selectable entry with an empty-string id.

List a project's epics so the agent can resolve epic uids for get_epic and card assignment. Returns each epic in display order (position ascending) with its uid, number, name, description (Markdown), color, start/end dates and card counts.

List a project's labels so the agent can reuse the existing taxonomy instead of creating near-duplicates on card writes. Returns each label in display order (position ascending) with its uid, name and position.

List the cards of one kanban list, or of the project's backlog when list_id is omitted or empty, in board display order (top of the column first, i.e. placement position descending — the same order the product UI shows). Filters combine with AND: epic_id, label_id, assigned_user_id and reporter_id take uids (an unknown uid matches nothing); due_date keeps cards due on or before the given date. Returns action-sufficient card summaries (uid, title, list + position, epic, labels, assignees, reporter, due date) ready for get_card / move_card / update_card, paginated with limit (default 50, max 100) and offset; total_count is the full filtered count.

Title-substring card search within one project (kanban board and backlog), matching the product's in-project live card search exactly (database case-insensitive substring on the card title only — descriptions and comments are not searched; use the search tool for full-text search across all content types), ordered newest-created first. Returns action-sufficient card summaries (uid, title, list placement + position, epic, labels, assignees, reporter, due date); a query with no matches returns an empty cards array, not an error. Paginate with limit (default 50, max 100) and offset; total_count is the full match count.

List the cards needing attention on a project's kanban board — the same lists as the product's Metrics pages. Kinds: stuck (sitting in a column, not backlog/Done, unmoved for over 7 days; longest-stuck first), blocking (undone cards that other cards are blocked by), overdue (due within the next 7 days or already past due; soonest first). kind selects one list or 'all' (default). Optionally filter by an assignee uid or the literal 'unassigned'. Each requested section returns card summaries ready for get_card / move_card / update_card, capped at limit with the full total_count. Requires a Pro or trial workspace.

One-call counts of the cards needing attention on a project's kanban board: overdue_cards_count, blocking_cards_count and stuck_cards_count — the same definitions as list_attention_cards, which returns the cards behind each count. Cheap; call this first to decide whether a deeper look is worth it. Requires a Pro or trial workspace.

List a project's roadmap slots overlapping a date window (default: this month through five months out). A slot schedules an epic between two dates and can carry assignees; one epic may hold several slots, overlaps included — that is by design. Returns at most 200 slots — narrow the window if capped. Requires a Pro or trial workspace.

Schedule an epic on the project roadmap: a slot from start_date to end_date, optionally with assignees. An epic may hold several slots and overlaps are allowed by design — check list_roadmap_slots first if you mean to extend an existing slot rather than add one. Requires a Pro or trial workspace.

Update a roadmap slot: reschedule or resize (start_date/end_date), move it to another epic of the same project (epic_id), or set its assignees. Only supplied fields change, EXCEPT assigned_to which REPLACES the full assignee set — read the slot first and send everyone who should remain. Slot uids come from list_roadmap_slots. Requires a Pro or trial workspace.

PERMANENTLY delete a roadmap slot (and its assignee links). This cannot be undone — there is no trash for roadmap slots. The epic itself is not touched; to reschedule, prefer update_roadmap_slot. Requires a Pro or trial workspace.

Create a new label on a project by name. If a label with the same name already exists (case-insensitive), the existing label is returned unchanged instead of creating a near-duplicate. The new label is appended at the end of the display order.

Create a card on a project's kanban board. Only project_id and title are required. Omit list_id to put the card in the backlog; omit position to join the end of the queue (move_card documents the position contract). description is AgileHero Markup — never markdown or HTML; read get_ahm_spec first. epic_id and assignee uids must already exist (list_epics, list_project_users), while label names that do not exist yet are created on the project. estimation is Fibonacci complexity (0/1/2/3/5/8/13), not a time estimate. Checklists, links, attachments and card relations can all be supplied in this same call.

Update an existing card by its uid. For collections, prefer the add_*/remove_* delta fields (safe incremental edits: add_labels, remove_assignees, add_checklist_items, check_items, …); the plain collection fields (labels, assigned_to, checklists, cards_relations, links, attachments) REPLACE the prior state destructively and cannot be combined with their deltas. Use move_card to change list or position, and preview_description_update / update_description to edit the description.

Soft-delete a card by its uid: it leaves the board and every listing, its relations to other cards are removed, any estimation session on it is deactivated, and whiteboard elements linked to it are unlinked. The epic it belonged to is not deleted. There is no undelete through MCP.

Move a card to a different list (or change its position within the same list). Only cards on a kanban board can be moved; cards on retrospective boards are rejected. Pass an empty string for list_id to move the card to the kanban backlog. A list is displayed top-down from its highest position, so position 0 is the BOTTOM of the list. Omit position to join the end of the queue (the bottom, position 0) in the backlog and in to_do and in_progress lists, or the top of a done list.

Create an epic on a project. Only project_id and name are required. description is AgileHero Markup — never markdown or HTML; read get_ahm_spec first. Assignee uids come from list_project_users. Checklists, links and attachments can be supplied in this same call. Returns the new epic uid — what create_card / update_card take as epic_id, and what create_roadmap_slot schedules.

Update an existing epic by its uid; only supplied fields are changed. For collections, prefer the add_*/remove_* delta fields (safe incremental edits); the plain collection fields (assigned_to, checklists, links, attachments) REPLACE the prior state destructively and cannot be combined with their deltas. Use preview_description_update / update_description to edit the description.

Soft-delete an epic by its uid. Its cards are NOT deleted — they stay on the board, detached from the epic. The epic's roadmap slots ARE permanently deleted (a slot schedules an epic, so it is meaningless without one), and whiteboard elements linked to the epic are unlinked.

Add a comment to a card or to an epic. Provide exactly one of card_id or epic_id. Content is AgileHero Markup (AHM, comment surface: no tables, media, colors, alignment, or discussions) — never markdown or HTML; read get_ahm_spec first. The comment is attributed to the signed-in user this client acts as and appears in subsequent get_card / get_epic responses. Comments cannot be edited via MCP; delete_comment removes your own (correct mistakes by delete + repost). Pass parent_comment_id to reply to an existing comment. Threads are one level deep: replying to a reply attaches the new comment to that reply's thread root instead, so do not attempt to nest replies. The parent must be a comment on the same card or epic — a uid from anywhere else is rejected.

Delete a comment YOU posted (comments are attributed to the signed-in user this client acts as — other people's comments cannot be deleted). The correction pattern is delete + post a corrected comment with create_comment. A deleted comment that has replies remains visible as a tombstone in its thread. Comment uids come from get_card / get_epic.