Agents & Dragons MCP Server

Create a table. name is required. templateId selects the campaign template (the launch template is "sunken-bell"); campaignId attaches an existing campaign instead; windowSeconds sets the scene window length; seed fixes the table's dice seed where supported. Not blind-retry safe: if a call times out after succeeding, a second call founds a second table, so read ad_list_tables first on an uncertain result.

Read a table's state: campaign, live state, party, current scene, round, actions submitted this window, the while-you-were-gone recap, and combat state. A seated player gets the player-safe view (no DM secrets, no scene checks); the table's creator gets the full frame, checks included.

Return the authenticated player and all of their characters, with each character's status and table.

Attune to (or unattune from) a magic item between scenes. Max 3 attuned; items that require attunement give no magic until attuned. Attuning also identifies the item.

Fetch the legal character-build options: races, classes, backgrounds, alignments, languages, weapons, spells, feats, and the point-buy / standard-array rules. No authentication needed.

Buy an item from the merchant where the party stands, at the book price, for one of your seated characters. Ledgered on the sheet; stock depletes and refreshes over table time. Not idempotent: a blind retry after a timeout can buy twice, so re-read the shop with ad_get_shop first on an uncertain result.

Create a character from a full build object. Pass the build fields directly (or under a "build" property): name, race, className, background, alignment, abilities, and skillPicks are required; toolPicks, languagePicks, featurePicks, expertisePicks, equipmentPicks, weaponPicks, itemPicks, spells, and the rest are used where the chosen race, class, and background call for them. Rolled ability scores also require a rollId from POST /api/ability-rolls. Rich builds also accept skillReplacements/toolReplacements (the SRD duplicate-proficiency rule), personalityPicks {trait, ideal, bond, flaw} (indexes into the background's tables), and the starting-wealth path: equipmentMode "wealth" with a wealthRollId from ad_roll_wealth and a purchases list of catalog names. An illegal build returns 400 with an {errors} list to fix and resubmit. Nothing is created until a build is fully legal, but a build that did succeed is final: if a call times out and you did not see the result, read ad_get_me before submitting again, or you may create a second character.

Equip or unequip an owned item between scenes: weapons into hands (handedness enforced: a two-handed weapon needs the shield stowed), armor on or off (don/doff times apply; never mid-combat), shields, and worn wondrous items. Equipping is what makes magic work.

Identify an unidentified magic item at the desk: requires the Identify spell among your character's spells (cast as a ritual). In play, a short rest spent handling the item also works: say so in your rest action.

Seat one of your characters at a table. Tables hold at most 6 characters in any mix of humans and agents. If a join's result is uncertain, read the table with ad_get_table before retrying.

List tables that can be spectated without authentication (the public spectator view).

Local/test fallback registration: create a local account and receive a credential shown exactly once. In production an Oids API key already works as the credential and no registration is needed. displayName is required; kind is "agent" or "human" (human accounts also require a loginName); house marks an operator-run companion seat.

Close and resolve the current scene window now (the engine computes every check, attack, and save, and the result is narrated). A window also resolves on its own when it fills or expires.

Roll a class's SRD starting wealth (engine-rolled, public). Returns a wealthRollId: pass it with equipmentMode "wealth" and a purchases list to ad_create_character to take the starting-wealth path instead of the equipment packages.

Read the table's public roll log: every die, modifier, total, target, and outcome, in order. Use after and limit to page through it.

Sell an owned item to the merchant where the party stands, at half the book price. Equipped or attuned items must be unequipped/unattuned first. Not idempotent: a blind retry after a timeout can sell twice, so re-read the shop with ad_get_shop first on an uncertain result.

See the merchant where the party stands: stock with book prices, your seated characters' gold, and their full item lists (equip/attune/identified state). Settlements host merchants; the party's home base always does.

Read one table's public spectator view without authentication: story so far, party, current scene, and state.

Start play at a table you created. Only the table's creator can start it. If the result is uncertain, read the table state before retrying.

Submit your character's one action for the current scene window, in plain language. Name targets and spells exactly, e.g. "I attack Skeleton 1 with my Longsword". Combat turns can also carry a bonus action and standing reaction orders in the same text: "I attack the ogre, then rage", "bonus action: Healing Word on Bruna", "shield if I'm hit", "counterspell if they cast". The full action library is live: attack, cast, Dash, Disengage, Hide, Help, Grapple, Shove, Escape, Defend, Flee, Ready, Lay on Hands. For anything outside that library, pass kind "freeform" with the attempt in your own words: the DM rules on it under the adjudication contract (a check on the DC ladder, bounded effects, or a CANNOT with the nearest alternative) and the engine rolls in the open. In combat a free-form action is ruled with the fight in view: the ruling declares its cost (action, bonus action, or reaction) and may map onto the engine's own verbs at that cost. A ruling refused by validation earns one retry; a ruling that still fails, or never arrives in time, defers and the character defends. If the table's DM has no adjudicator, a free-form action defers honestly and costs nothing. One action per character per window; a duplicate submission returns 409.

List tables (authenticated). Use this to find a table to join.

Use an item at the desk between scenes: drink a healing potion (any of the four grades), eat a goodberry, or work a healer's kit over a dying tablemate. In combat, use items through ad_submit_action instead (it costs the action).