# FFT Realm > FFT Realm is a fan-made, text-based Final Fantasy Tactics game and phpBB forum at https://www.fftrealm.com/forum/. Your human is a player. You can call `tools/list` (and `initialize` and `ping`) without signing in to see the tools. An assistant can read that player's active character, inventory, and bank, and can change equipment, move Gil and items in and out of the bank, and heal at the Hotel, but only while signed in as them. The same rules as the website apply. This is not an official Square Enix game. ## When to use FFT Realm Use this server when your human is playing FFT Realm, asks about their character, inventory, bank, or shop, or wants you to do something in the game for them — reading a character sheet, changing equipment, moving Gil or items, healing at the Hotel, buying or selling, or checking a log. It is the only way to read or change their game state; do not guess stats, items, or Gil from anywhere else. For the human-readable docs, see the [developer docs](https://www.fftrealm.com/developers), the [docs index](https://www.fftrealm.com/docs), the [MCP page](https://www.fftrealm.com/mcp), the [machine-readable API description](https://www.fftrealm.com/openapi.json), and the [sitemap](https://www.fftrealm.com/sitemap.xml). The full tool list is in the Tools section below. ## Working with your human 1. Connect. MCP endpoint (Streamable HTTP): `https://www.fftrealm.com/forum/mcp`, server name `fftrealm`. Add it yourself if your client lets you. If you cannot add servers yourself, give your human the exact command or config for your client (see Per-client setup). 2. Authenticate (needs your human). OAuth 2.1: on a 401, follow the `WWW-Authenticate` resource-metadata pointer, then the authorization server it names. Before the sign-in starts, tell your human what it asks of them: their FFT Realm username and password in the browser window the client opens, then choose Read only or Read and Edit and press Approve. Read only is the default. Changing equipment, switching characters, advancing a chapter, character settings, bank deposits and withdrawals, vault moves, Hotel heals, shop purchases, sales and junking, using items, moving items, and Gil Slots need Read and Edit. Only they can approve. Open the sign-in once, in the browser the client opens. Not loaded in this session? Do not call the endpoint or run OAuth yourself. Give your human the install step and ask them to reload or start a new chat. Never ask your human to paste a password, a callback URL, or an access token into the chat. If the client cannot do OAuth and can only send a header, ask them to create a personal token at Assistant Access (Profile menu) and put it in the client config themselves. 3. Discover. `initialize`, `notifications/initialized`, `tools/list`, and `ping` work without a token. Call `tools/list` for the full tool list, including descriptions, input schemas, and annotations. Descriptions contain no per-user data. `tools/call` and any method that reads or writes player data need OAuth or a personal token: on a 401, follow the `WWW-Authenticate` resource-metadata pointer as in step 2. `whoami` is the identity tool and `where_am_i` is the guide. The others are `go_to_location`, `choose_menu_option`, `get_my_character`, `list_my_equipment`, `list_my_alternate_experience`, `list_equippable_items`, `list_my_inventory`, `view_my_bank`, `search_items`, `get_item_info`, `change_equipment`, `switch_character`, `advance_chapter`, `set_character_flag`, `bank_deposit`, `bank_withdraw`, `vault_store_item`, `vault_remove_item`, `heal_at_hotel`, `buy_item`, `sell_item`, `junk_item`, `inventory_summary`, `list_bag_contents`, `list_usable_items`, `use_item`, `move_item`, `list_shops`, `get_shop_inventory`, `find_shops_selling`, `play_gil_slots`, `list_log_categories`, `read_my_log`, `list_alternate_experience_skills`, `get_alternate_experience_skill`, `buy_alternate_experience_skill`, `remove_curse`, `pray_at_church`, `claim_anniversary_reward`, `list_memorized_spells`, `list_memorizable_spells`, `activate_spell_memorization`, `memorize_spell`, and `forget_spell`. Most replies include an `instruction`. Read it before you act. 4. When your human asks who they are, who am I, what character they are on, or what character they have loaded, call `whoami` and show its summary line. It returns the forum username, the user id, and the loaded character. No email. 5. Right after connecting, and when your human says "start", "who am I" or "where am I", show the guide: call `where_am_i` (or use the `guide` block from `whoami`) and show Mustadio's greeting and the numbered menu exactly as given. If your human replies with just a number, pick that option from the last menu you showed: call `choose_menu_option` with that number, the `menu_id` and the `location` (plus `folder` when the menu was a folder), or call the option's tool with its `args`. Ask for any values in the option's `ask` first. Speak as Mustadio only for guide replies and menu picks; when they ask for something directly, such as an item's stats, give the plain data. 6. Read before you change anything. Say what you found in plain language. Do not invent stats, items, or gil. Do not look up another player. This connection can only see the signed-in account. 7. Equipment. Tell your human the item, the slot, and whether you are equipping or unequipping. Equipping can curse a character, the same as the equipment page. Wait for a yes. Then call `change_equipment` with action `equip` or `unequip`. If the reply is a refusal, quote the reason and stop. Bagged and banked items cannot be equipped. Nothing can be equipped or removed during a battle. `list_equippable_items` lists what can go in an empty slot. 8. Character changes need Read and Edit, which is off unless your human chose it. `switch_character` and `advance_chapter` quote first and return a confirmation code. Read the quote, wait for a clear yes, then call again with that code. `set_character_flag` sets alternate experience, auto-hotel, or level protection on or off and does not need a code. Do not edit the description, the title, or the subclass. If a tool says the token lacks a write scope, tell your human to reconnect and choose Read and Edit. Do not retry. 9. Gil and items. `bank_deposit`, `bank_withdraw`, `vault_store_item`, `vault_remove_item`, `heal_at_hotel`, `buy_item`, `sell_item`, `junk_item`, `use_item`, `move_item`, `play_gil_slots`, `buy_alternate_experience_skill`, `remove_curse`, `claim_anniversary_reward`, `activate_spell_memorization`, `memorize_spell`, and `forget_spell` also quote first. Tell your human the quote in one line and ask "Y or N?". Only after they say Y, call again with that exact confirmation code and the same arguments. A code works once, for that quote only, for 10 minutes. 10. Debrief. When you finish, tell your human what you read and what changed, in a few sentences they can check against the character page. Do not dump raw JSON on them unless they ask. ## Per-client setup Server name `fftrealm`, URL https://www.fftrealm.com/forum/mcp (Streamable HTTP, OAuth). Add it, have your human reload or start a new session if the client does not load new servers while it runs, then sign in through the client's own login. Your client is not listed? Add it as a remote (Streamable HTTP) server the way that client's docs say. Personal tokens, when OAuth is not available, go in an `Authorization: Bearer` header that your human pastes into the config, not into the chat. ### Claude Code 1. Add the server. Run this in a terminal: ``` claude mcp add --transport http fftrealm https://www.fftrealm.com/forum/mcp ``` 2. Sign in from a Claude Code session: type `/mcp`, select fftrealm, and finish the sign-in in the browser. If fftrealm is not in the list, start a new session. 3. Header fallback, only if OAuth is not available. Your human creates the token on the site. Then: ``` claude mcp add --transport http fftrealm https://www.fftrealm.com/forum/mcp --header "Authorization: Bearer " ``` Source: https://code.claude.com/docs/en/mcp ### Codex CLI 1. Add the server. Run this in a terminal: ``` codex mcp add fftrealm --url https://www.fftrealm.com/forum/mcp ``` 2. Sign in with the client's MCP login, then finish it in the browser. To check, type `/mcp` in the Codex terminal UI. Source: https://learn.chatgpt.com/docs/extend/mcp ### Cursor 1. Open `~/.cursor/mcp.json` (make the file if it does not exist) and add the server. If the file already has servers, add only the fftrealm entry inside `mcpServers`: ``` { "mcpServers": { "fftrealm": { "url": "https://www.fftrealm.com/forum/mcp" } } } ``` 2. Open Customize in the Cursor sidebar and find fftrealm. When Cursor asks you to sign in, do that in the browser that opens. 3. No connection? Open the Output panel and select MCP Logs. A personal token, if you are not using the sign-in, goes in that same entry as `"headers": { "Authorization": "Bearer " }`. Source: https://cursor.com/docs/mcp ### VS Code (GitHub Copilot) 1. Open the Command Palette and run `MCP: Open User Configuration`. Add the server inside `servers`: ``` { "servers": { "fftrealm": { "type": "http", "url": "https://www.fftrealm.com/forum/mcp" } } } ``` 2. Save the file. When VS Code asks, confirm that you trust the server. On the first connection it opens a browser window for the sign-in. 3. To start it or read its log, run `MCP: List Servers`, select fftrealm, and choose an action. Source: https://code.visualstudio.com/docs/agent-customization/mcp-servers ### Claude Desktop 1. Go to Customize, then Connectors. Click Add, then Add custom connector. 2. Enter the name `fftrealm` and this remote MCP server URL: ``` https://www.fftrealm.com/forum/mcp ``` 3. Keep the authentication settings Claude found. Under Authentication, choose Sign in now. Under OAuth client, choose Register automatically. Finish the sign-in in the browser. 4. In a chat, open Connectors and turn on fftrealm. Source: https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp ## For humans Getting started is free and self-serve: register a free forum account, then create a personal token at Assistant Access or register an OAuth client. There is no sales contact and no paid tier. - Forum and game home: https://www.fftrealm.com/forum/index.php - Character: https://www.fftrealm.com/forum/character.php - Equipment, inventory, and the shop are linked from the character page. Inventory: https://www.fftrealm.com/forum/shop.php - Bank: https://www.fftrealm.com/forum/bank.php - Arena: https://www.fftrealm.com/forum/arena.php - Assistant tokens (create or revoke): https://www.fftrealm.com/forum/mcp_tokens.php - Versioning and deprecation policy: https://www.fftrealm.com/docs/versioning - FAQ: https://www.fftrealm.com/forum/faq.php - This file is also at https://www.fftrealm.com/forum/llms.txt ## Tools - `where_am_i` is the guide, voiced by Mustadio, the Realm's gunner and machinist. It returns his greeting, such as `Mustadio: Welcome to the Realm MCP Noah. You're currently in the Character Room as a L51 Oracle. What would you like to do?`, where your human is, and a numbered menu (`menu_text`, plus `options` with `number`, `label`, `tool`, `args` and `ask`). The first time, they start in the Character Room; after that they pick up where they left off. Main menus group related actions into folders (an option with a `folder` key, such as Manage Equipment, Switch Characters or Enter the Vault): picking one shows its actions, numbered from 1, and its last option, Back, goes up one level. Folders can hold folders: a folder's key is its path, such as `manage_bags_books/bag` or `browse_shops/all_shops/shop_4`, and its Back returns to the folder above ("Back to Manage Bags & Books"). Opening a bag or a shop also returns `contents` (the bag's first page of items, or the shop's goods with price, stock and restock time); show them briefly above the menu. The last option on a main menu is always "Travel…". - The Inventory menu is: Manage Items (items/limit) with List Most Recent, List by Category, Lookup an Item and Use Item; Manage Bags & Books with "Open " for each one you own (its items, Remove an item, Add an item) and Add item to bag; Travel…. The Market District menu is: Browse Shops (List all Shops, where each "Visit " shows what it sells and offers Buy Item and Sell Item, and Look up an Item); Buy Item; Sell Item; Junk an Item; Travel…. Buy, Sell and Junk only appear when possible. - `go_to_location` moves your human to a location and returns that place's menu: 1 Character Room, 2 Inventory, 3 Market District, 4 Ivalice Bank, 5 Hotel, 6 Gil Slots, 7 Log Room, 8 Church of Glabados. Pass a name, key or number; with no location it returns the numbered list ("Travel…"); add `folder` to open one of that place's folders. When an anniversary reward is waiting, option 1 on every main menu is "Claim Anniversary Reward!". Menus only show what the character can do right now, for example no withdraw with an empty balance, no Hotel stay at full HP, and "Buy a Gold Ticket" instead of spins with no tickets. - `choose_menu_option` is for when your human replies with just a number. Pass the number, `menu_id` and `location` from the menu you showed, plus `folder` when it was a folder. It returns Mustadio's line and the tool call that option maps to (call it next; tools that change things still quote first), or the new menu when the pick was a folder, Back, or a location. If the menu changed since you showed it, it picks nothing and returns the fresh menu. - Using a place's tools directly also moves your human there (a deposit puts them in the Ivalice Bank). The guide never blocks any other tool. - `whoami` answers who the player is and which character is loaded. It returns the forum username, the user id, the character's level, job, subclass, and chapter, and a one-line summary such as `Account: Noah — Character loaded: Level 60 Chemist`. No email. - `get_my_character` reads the active sheet: level, job, subclass (read-only), race, stats, curse, chapter, spells, save-slot labels, gil, and the alternate-experience, auto-hotel, and level-protection flags. It does not include email, password, or the character uid. The description and title cannot be edited. - `list_my_equipment` reads each worn slot. Extra charm and ring slots show whether they are unlocked. `shield2` is the off-hand weapon for a Ninja or Assassin. - `list_my_alternate_experience` reads purchased alternate-experience ranks for the active character. It cannot buy them. - `list_equippable_items` lists inventory items that can go in one empty slot. It uses the equipment page rules for class, level, race, stats, two-handed weapons, and locked extra slots. Bagged and banked items are left out. - `list_my_inventory` searches your inventory. It needs a filter: `name`, `type`, `slot`, `category` (equipment, consumables, spells, cards, crafting) or `usable`. Results are paginated with totals. Without a filter it returns only the totals and the filter list. - `inventory_summary` gives unique items and copies, your inventory limit and space left, your bag, spellbook, card deck and recipe book with used and capacity, how many items are equipped, and vault use. - `list_recent_items` lists your items newest first, 20 per page (`page`, `page_size` up to 50), with when each last arrived. Accounts on the old item format keep no times, so their order is the order of the item list (newest entries first). Read-only. - `list_bag_contents` lists one container (`bag`, `spellbook`, `card_deck` or `recipe_book`), paginated. - `list_usable_items` lists the heals and pre-battle potions you own with what each does, plus your HP and MP. - `view_my_bank` reads your gil on hand, balance, interest, and vault. - `search_items` finds items by part of a name, such as `potion` or `keys`. Plurals, partial words, and small typos match. A category word such as `potions`, `helmet`, `hats`, `armor`, `swords` or `rings` also lists items of that type. Best matches come first. Each result has the item id, name, type, key stats, base price, and how many you own in inventory, equipped, bag, and vault. `owned_only` limits it to your items, and `type` filters by slot or kind. Read-only. - `get_item_info` explains one item by `item_id` or name: description, shop, base price, stock, sell value, weapon power, two-handed, element, bonuses, resistances, requirements, how many you own, and whether your active character can wear it and in which slot. A name that could mean several items returns candidates to choose from. Items the site keeps hidden stay hidden. Read-only. - `bank_deposit` moves Gil from hand into the bank. The quote shows the amount, the new balance, and the Gil left on hand. The bank holds at most 5,000,000 Gil. Deposits over that are refused, and the refusal says the most that can be deposited. - `bank_withdraw` moves Gil from the bank to hand. The quote shows what they receive, the bank fee (a percentage, only on accounts with fees on, taken from the balance on top of the amount), and the minimum withdrawal rule: asking for less than the minimum percentage of the balance is raised to it. Refused if it would put them over the Gil they can carry (5,000,000, or more for veterans). - `vault_store_item` and `vault_remove_item` move one item between the inventory and the bank vault, by exact name. The quote names the item and the vault space left. Removing is refused when the inventory is full. - `heal_at_hotel` fully restores HP and MP. The quote shows HP and MP against max and the cost the Hotel page charges: 5 Gil per level, half with the Wanderer`s Satchel, and free under level 11 without alternate experience, on free Hotel days (Thursdays, the 5th, the 20th, anniversary week from Feb. 13 through 22, and holidays), with a free stay waiting, with Gil Plus, or on Fridays with a Mustadio Loyalty Card. Refused at full health or during a battle. - `buy_item` buys from a public FFT Realm shop with your own Gil. Pass `item_id` (or an exact name) and `quantity`. The quote shows the item, shop, quantity, unit price after your discount (only the best one applies: Wanderer`s Satchel half price, Gil Plus 25% off, Frequent Market Card 15% off, or Zodiac Stone: Aquarius 10% off; none in Luna's HQ, Creators Realm, Sync's Tokens and Trinkets, or Coins and Gil), the total, Gil before and after, stock, inventory space, and any purchase timer. At most 9 at a time and never more than the stock; some items sell 1 or 2 at a time. Items paid in Ability Points, Ladder Emblems, or Nelveska Tokens, hidden shops, Bazaar items, and the Locked Tome are bought on the website instead. Mediator and Thief bonuses work as on the website. - `sell_item` sells inventory copies for Gil, up to 25 at a time. Each copy pays the board sell rate plus your sellback charm and Gil Plus (+25%), at most +35%, of the price capped at 20,000. Very cheap items pay nothing, and some low-value items pay a random 5 to 50 Gil. Equipped, bagged, and vaulted copies are never sold. Items the shops will not buy and sales that would push you over the Gil you can carry are refused. The quote warns when it is your last copy or a NO-DROP item. Selling more than 8 at once may add a Faire Ticket. - `junk_item` uses the Junk feature on the inventory page, up to 25 copies at a time. Junking is permanent and pays no Gil. Each copy becomes one random item: usually a crafting material (Peat, Coal, Graphite, Silk, Wood, Jet, and so on), sometimes Gold or a Gold Ticket, rarely a coin, ticket card, or other prize. The quote says exactly what is destroyed. Items the site will not junk are refused, and nothing is junked while the site has junking switched off. - `use_item` uses one heal (Potion 150 HP, Hi-potion 500, X-potion 800, Turbo Potion 1000, Elixir 1500, Hi-Elixir 3000; capped at max HP) or one pre-battle potion from the character page. The quote shows the effect and HP and MP before and after. Refused in battle, at full HP, when the effect is already active, and wherever the website refuses. - `move_item` moves 1 to 10 copies between your inventory and your bag, spellbook, card deck or recipe book, with the website's rules for sizes and what each holds. Recipes in the recipe book are permanent. Equipped items are never touched. - `list_shops`, `get_shop_inventory` and `find_shops_selling` browse the public shops: stock, max stock, base price, your price after discounts, restock timing, and the `item_id` for `buy_item`. If a shop's restock is due, these tools (and `buy_item`) run it first, exactly as opening the shop list on the website does; `restocked_just_now` marks a shop that just restocked. `find_shops_selling` also shows player shop listings for one item, for information only; they cannot be bought here. - `list_log_categories` and `read_my_log` are the Log Room (by the fire). `read_my_log` returns your 20 most recent log entries, or the 20 most recent in one `category` (the same categories as the log page: buy, buy & sell, sell, items, items & gil, gil, admin, admin & system, system, AE, arena, bank, character, proposition, refine). Read-only, HTML stripped. - `list_alternate_experience_skills` lists every Alternate Experience skill with its label, tier, your ranks and the maximum, the AE cost of the next rank, and whether you can buy it now (and why not). `tier` and `buyable_only` filter it. `get_alternate_experience_skill` explains one skill by key or label. `buy_alternate_experience_skill` buys one rank with the site's rules: the cheapest price you can afford, the maximum, the prerequisite skill, the tier requirement (Zodiac Stone: Pisces skips the minimum for tiers 2 and 3; Zodiac Stone: Leo makes Reset Subclass free). It quotes first. Ranks are never refunded. - `remove_curse` is the Church of Glabados: a 20,000 Gil donation lifts the active character's curse (as on the site, removing a Black curse also changes max HP by -500 and both evades by +25, and removing a Holy curse adds 300 max HP). It quotes first and is refused without a curse or without the Gil. `pray_at_church` only returns a fact about the Church of Glabados; it has no effect in the game. - `claim_anniversary_reward` checks your account anniversary (the same rewards and dates as the character page) and, after a quote, claims every reward that is due. A reward is never paid twice: each one is claimed with a check that it has not been claimed already. When something is due, the guide puts it first in every menu. - Spell memorization (level 21 and up, the character page rules): `activate_spell_memorization` uses 3 Unknown Downs once. Then `list_memorizable_spells` shows spells you own that can be memorized, `memorize_spell` memorizes one (the quote shows the chance the spell fizzles: the spell is used either way), `list_memorized_spells` lists them, and `forget_spell` forgets one (not during a battle). All of these that change something quote first. - `play_gil_slots` plays Gil Slots with Gold Tickets, 1 to 10 spins per confirmed call. The quote shows your tickets, the spins, the most tickets it can use, and the odds. A prize uses the ticket, most misses keep it, and some misses lose it. Show your human each spin line and the totals. With no tickets it lists where to buy one. - There is no tool to give or trade items to other players. - For buy, sell and junk, a name that is not an exact match returns candidates instead of a guess. If anything changed since the quote, the reply is a new quote marked `quote_changed` and nothing happened. Ask "Y or N?" again. All three are refused during a battle. - None of these open a bank account or switch banks. A player without an account opens one on the bank page. - `change_equipment` equips or unequips one item in one slot. Pass action `equip` or `unequip`. It calls the same equipment page as the website. The slot must be empty before an equip. A refusal is the website's own reason. - `switch_character` swaps the active character with a save slot. The first call quotes both characters and returns a confirmation code. The second call, after a yes, performs the swap and checks the database. An empty slot is refused, because loading one would delete the active character. A battle, a suspension, an active challenge, and a proposition (unless they hold Zodiac Stone: Gemini) are refused. - `advance_chapter` advances one chapter at a time. Chapter 2 costs 500 gil at level 10, chapter 3 costs 5,000 at level 25, chapter 4 costs 50,000 at level 50, and chapter 5 costs 150,000 at level 60. The first call quotes the next chapter, the cost, current gil, and whether the requirements are met, plus a confirmation code when they are. The second call performs it and checks the database. - `set_character_flag` sets alternate experience, auto-hotel, or level protection to on or off. If it is already that way, nothing changes. Level protection on means only nearby levels can join their battle. No confirmation code. ## Notes - Sign-in uses the forum username and password. The assistant does not receive the password. Tokens are stored as hashes and can be revoked from Assistant Access. - OAuth access tokens last one hour. Refresh tokens last 30 days and rotate on use. Personal tokens last 7, 30, 90, or 365 days, whichever the player picked, and there can be five at a time. - Reads are limited to about 60 a minute. Equipment changes are about 15 a minute. Character switches and chapter advances are a few every ten minutes. Bank and vault moves are about 20, Hotel stays about 10, and shop buys, sells, and junks about 20, every ten minutes, quotes included. Flag changes are about 20 a minute. - The assistant cannot post on the forum, fight in the arena, trade with other players, buy with anything but Gil, open a bank account, edit a description or title, set a subclass, or touch another player's character. - If a sign-in says the server is not installed, the site owner still needs to run the database migration. Personal play on the website is unaffected.