{
  "openapi": "3.1.0",
  "info": {
    "title": "FFT Realm MCP API",
    "version": "2026-11-20",
    "description": "Machine-readable description of the FFT Realm MCP server (Streamable HTTP JSON-RPC) and its OAuth 2.1 endpoints. The server lets an assistant read the signed-in player's character, inventory, and bank, and change equipment, move Gil and items, and heal at the Hotel, under the same rules as the website. initialize, notifications/initialized, ping and tools/list are public, so an agent can preview all tools without signing in. tools/call needs an OAuth token from a signed-in player.; see llms.txt for the human setup steps. Versioning and deprecation policy: https://www.fftrealm.com/docs/versioning.",
    "contact": {
      "email": "support@fftrealm.com"
    },
    "license": {
      "name": "Fan project — not affiliated with Square Enix"
    }
  },
  "servers": [
    {
      "url": "https://www.fftrealm.com"
    }
  ],
  "tags": [
    {
      "name": "mcp",
      "description": "JSON-RPC calls to the MCP server"
    },
    {
      "name": "oauth",
      "description": "OAuth 2.1 discovery and token endpoints"
    }
  ],
  "paths": {
    "/forum/mcp": {
      "post": {
        "tags": [
          "mcp"
        ],
        "operationId": "callMcpTool",
        "summary": "Call one MCP tool (JSON-RPC 2.0 over Streamable HTTP)",
        "description": "Send a JSON-RPC 2.0 request with a `method` naming one of the tools below and `params` for that tool. initialize, notifications/initialized, ping and tools/list are public, so an agent can preview all tools without signing in. tools/call needs an OAuth token from a signed-in player. Call the `tools/list` method first to discover each tool's parameters. Tools that change anything quote first and need a Read and Edit grant; the reply carries a confirmation code to send back with the same arguments. Available tools:\n- `activate_spell_memorization`: uses 3 Unknown Downs once.\n- `advance_chapter`: advances one chapter at a time.\n- `bank_deposit`: moves Gil from hand into the bank.\n- `bank_withdraw`: moves Gil from the bank to hand.\n- `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).\n- `buy_item`: buys from a public FFT Realm shop with your own Gil.\n- `change_equipment`: equips or unequips one item in one slot.\n- `choose_menu_option`: is for when your human replies with just a number.\n- `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.\n- `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`.\n- `forget_spell`: forgets one (not during a battle).\n- `get_alternate_experience_skill`: explains one skill by key or label.\n- `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.\n- `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.\n- `get_shop_inventory`: browse the public shops: stock, max stock, base price, your price after discounts, restock timing, and the `item_id` for `buy_item`.\n- `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.\n- `heal_at_hotel`: fully restores HP and MP.\n- `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.\n- `junk_item`: uses the Junk feature on the inventory page, up to 25 copies at a time.\n- `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).\n- `list_bag_contents`: lists one container (`bag`, `spellbook`, `card_deck` or `recipe_book`), paginated.\n- `list_equippable_items`: lists inventory items that can go in one empty slot.\n- `list_log_categories`: are the Log Room (by the fire).\n- `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).\n- `list_memorized_spells`: lists them, and `forget_spell` forgets one (not during a battle).\n- `list_my_alternate_experience`: reads purchased alternate-experience ranks for the active character.\n- `list_my_equipment`: reads each worn slot.\n- `list_my_inventory`: searches your inventory.\n- `list_recent_items`: lists your items newest first, 20 per page (`page`, `page_size` up to 50), with when each last arrived.\n- `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`.\n- `list_usable_items`: lists the heals and pre-battle potions you own with what each does, plus your HP and MP.\n- `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).\n- `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.\n- `play_gil_slots`: plays Gil Slots with Gold Tickets, 1 to 10 spins per confirmed call.\n- `pray_at_church`: only returns a fact about the Church of Glabados; it has no effect in the game.\n- `read_my_log`: are the Log Room (by the fire).\n- `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).\n- `search_items`: finds items by part of a name, such as `potion` or `keys`.\n- `sell_item`: sells inventory copies for Gil, up to 25 at a time.\n- `set_character_flag`: sets alternate experience, auto-hotel, or level protection to on or off.\n- `switch_character`: swaps the active character with a save slot.\n- `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.\n- `vault_remove_item`: move one item between the inventory and the bank vault, by exact name.\n- `vault_store_item`: move one item between the inventory and the bank vault, by exact name.\n- `view_my_bank`: reads your gil on hand, balance, interest, and vault.\n- `where_am_i`: is the guide, voiced by Mustadio, the Realm's gunner and machinist.\n- `whoami`: answers who the player is and which character is loaded.",
        "security": [
          {
            "FFTRealmOAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response (result or error).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          },
          "401": {
            "description": "Not signed in, or the token lacks the scope the tool needs. The response names the scope; the client follows the WWW-Authenticate resource-metadata pointer to sign in.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed (the MCP endpoint accepts POST only). JSON error body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. JSON error body; the Retry-After header says when to retry.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ]
      }
    },
    "/forum/mcp/.well-known/oauth-protected-resource": {
      "get": {
        "tags": [
          "oauth"
        ],
        "operationId": "getProtectedResourceMetadata",
        "summary": "Protected-resource metadata (RFC 9728)",
        "description": "Returns the protected resource's metadata: the resource URL, its authorization servers, and the scopes it supports.",
        "responses": {
          "200": {
            "description": "Protected-resource metadata document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resource": {
                      "type": "string"
                    },
                    "authorization_servers": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "scopes_supported": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "bearer_methods_supported": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "resource_name": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found. JSON error body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ]
      }
    },
    "/forum/mcp/.well-known/oauth-authorization-server": {
      "get": {
        "tags": [
          "oauth"
        ],
        "operationId": "getAuthorizationServerMetadata",
        "summary": "Authorization-server metadata (RFC 8414)",
        "description": "Returns the authorization server's metadata: issuer, authorization and token endpoints, registration endpoint, response and grant types, PKCE methods, and supported scopes.",
        "responses": {
          "200": {
            "description": "Authorization-server metadata document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Not found. JSON error body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ]
      }
    },
    "/forum/mcp/token.php": {
      "post": {
        "tags": [
          "oauth"
        ],
        "operationId": "exchangeToken",
        "summary": "OAuth 2.1 token endpoint",
        "description": "Exchanges an authorization code for access and refresh tokens, or a refresh token for a new access token. Grant types: authorization_code, refresh_token. PKCE S256 is required for the code exchange.",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "grant_type"
                ],
                "properties": {
                  "grant_type": {
                    "type": "string",
                    "enum": [
                      "authorization_code",
                      "refresh_token"
                    ]
                  },
                  "code": {
                    "type": "string"
                  },
                  "redirect_uri": {
                    "type": "string"
                  },
                  "code_verifier": {
                    "type": "string"
                  },
                  "refresh_token": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access_token": {
                      "type": "string"
                    },
                    "token_type": {
                      "type": "string"
                    },
                    "expires_in": {
                      "type": "integer"
                    },
                    "refresh_token": {
                      "type": "string"
                    },
                    "scope": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid grant or request. JSON error body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. JSON error body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ]
      }
    },
    "/forum/mcp/register.php": {
      "post": {
        "tags": [
          "oauth"
        ],
        "operationId": "registerOAuthClient",
        "summary": "OAuth 2.1 dynamic client registration (RFC 7591)",
        "description": "Registers a new OAuth client (dynamic client registration).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "redirect_uris": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "client_name": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Client registered.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid registration. JSON error body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HttpError"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "FFTRealmOAuth": {
        "type": "oauth2",
        "description": "OAuth 2.1 with PKCE (S256). Sign in through the browser the client opens; choose Read only or Read and Edit. Read tools need a read scope; tools that change anything need a write scope.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://www.fftrealm.com/forum/mcp/authorize.php",
            "tokenUrl": "https://www.fftrealm.com/forum/mcp/token.php",
            "scopes": {
              "character:read": "Read the signed-in player's character",
              "inventory:read": "Read the signed-in player's inventory",
              "bank:read": "Read the signed-in player's bank",
              "equipment:write": "Change the signed-in player's equipment",
              "character:write": "Change the signed-in player's character"
            }
          }
        }
      },
      "PersonalToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Personal token created at Assistant Access on the site, sent as an Authorization: Bearer header. Use only when OAuth is not available."
      }
    },
    "schemas": {
      "JsonRpcRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": [
              "2.0"
            ]
          },
          "method": {
            "type": "string",
            "enum": [
              "activate_spell_memorization",
              "advance_chapter",
              "bank_deposit",
              "bank_withdraw",
              "buy_alternate_experience_skill",
              "buy_item",
              "change_equipment",
              "choose_menu_option",
              "claim_anniversary_reward",
              "find_shops_selling",
              "forget_spell",
              "get_alternate_experience_skill",
              "get_item_info",
              "get_my_character",
              "get_shop_inventory",
              "go_to_location",
              "heal_at_hotel",
              "inventory_summary",
              "junk_item",
              "list_alternate_experience_skills",
              "list_bag_contents",
              "list_equippable_items",
              "list_log_categories",
              "list_memorizable_spells",
              "list_memorized_spells",
              "list_my_alternate_experience",
              "list_my_equipment",
              "list_my_inventory",
              "list_recent_items",
              "list_shops",
              "list_usable_items",
              "memorize_spell",
              "move_item",
              "play_gil_slots",
              "pray_at_church",
              "read_my_log",
              "remove_curse",
              "search_items",
              "sell_item",
              "set_character_flag",
              "switch_character",
              "tools/list",
              "use_item",
              "vault_remove_item",
              "vault_store_item",
              "view_my_bank",
              "where_am_i",
              "whoami"
            ],
            "description": "The tool to call. Call tools/list first to discover each tool's parameters."
          },
          "params": {
            "type": "object",
            "description": "Tool parameters. Discover them with tools/list; they vary per tool."
          },
          "id": {
            "type": [
              "string",
              "integer"
            ],
            "description": "Request id, echoed in the response."
          }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": [
          "jsonrpc",
          "id"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": [
              "2.0"
            ]
          },
          "result": {
            "description": "Tool result. Most replies include an instruction; read it before acting."
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "integer"
              },
              "message": {
                "type": "string"
              },
              "data": {}
            }
          },
          "id": {
            "type": [
              "string",
              "integer",
              "null"
            ]
          }
        }
      },
      "HttpError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "error_description": {
            "type": "string"
          },
          "code": {
            "type": "integer"
          }
        }
      }
    },
    "parameters": {
      "ApiVersion": {
        "name": "API-Version",
        "in": "header",
        "required": false,
        "description": "API version (date). Send the current version; older versions keep working for at least 30 days after a breaking change, with Deprecation and Sunset headers during that window. See /docs, Versioning and deprecation.",
        "schema": {
          "type": "string",
          "enum": [
            "2026-11-20"
          ],
          "default": "2026-11-20"
        }
      }
    }
  }
}