MGS Toolbox public API

Everything the MGS Toolbox shows is available here: 88 metals, 141 minerals, 350 ingredients, 54 potions, 58 gems, the Crafting Table rules, and the MGS Audio catalogue (tracks, composers, albums, packs, taxonomy). Every item carries url, the page to link, and embed_url, a card to iframe. Texts exist in English and French.

What you can build

Quick start

curl "https://michaelghelfistudios.com/api/v1/search?q=mithral"
curl "https://michaelghelfistudios.com/api/v1/metals/mithral?lang=fr"
curl "https://michaelghelfistudios.com/api/v1/minerals?system=cubic&gem_quality=true&limit=5"
curl "https://michaelghelfistudios.com/api/v1/audio/tracks/random?genre=Combat&type=music"

From a browser or a bot, no headers needed (CORS is open):

const res = await fetch('https://michaelghelfistudios.com/api/v1/ingredients/random?environment=swamp&lang=en');
const { data } = await res.json();
console.log(data.name, data.rarity, data.url);   // "Bog Iris", "uncommon", "https://…/apps/rerum/bog_iris"

Every response is an envelope:

{
  "success": true,
  "data": …,                       // an item, an array, or an object
  "meta": { "version": "v1", "lang": "en", "total": 141, "limit": 50, "offset": 0,
            "license": { "name": "…", "url": "…", "attribution": "…" } },
  "links": { "self": "…", "docs": "https://michaelghelfistudios.com/api/v1/docs" }
}

Conventions

Embeds & oEmbed

Cards

Every entry, track, artist and album has a card at /apps/embed/{kind}/{id} (kinds: metal, mineral, ingredient, potion, gem, track, artist, album). Options: ?lang=fr, ?theme=light|dark (default follows the visitor). The "Share" button on every encyclopedia page copies this for you. Minerals of the Crystal Forge show their rendered specimen (also image_url in the API and oEmbed's thumbnail_url); track cards play the site's 30-second preview — the JSON API itself still returns no audio URL.

<iframe src="https://michaelghelfistudios.com/apps/embed/metal/iron?lang=en" width="100%" height="340"
        style="border:0;max-width:480px" loading="lazy" title="Iron — Metal Encyclopedia"></iframe>

Cards post their height to the host page, so an iframe can fit its content:

window.addEventListener('message', (e) => {
  if (e.data?.type !== 'mgs-embed') return;
  document.querySelectorAll('iframe').forEach((f) => { if (f.src === e.data.href) f.height = e.data.height; });
});

oEmbed

Paste a page link into WordPress, Discord, Notion, Ghost, Discourse or any platform with oEmbed discovery and it becomes the card by itself: every page advertises https://michaelghelfistudios.com/api/v1/oembed?url=…. Integrators can call it directly:

curl "https://michaelghelfistudios.com/api/v1/oembed?url=https%3A%2F%2Fmichaelghelfistudios.com%2Fapps%2Fcrystal%2Fquartz&maxwidth=400"

Album player

Albums have a real player with a preview of every track: https://michaelghelfistudios.com/audio/embed/{albumId} (450px high). It is what oEmbed returns for an album page.

Whole encyclopedias

The encyclopedias themselves accept being framed (/apps/metals/, /apps/crystal/, /apps/rerum/), which is how the Foundry VTT module shows them inside a world.

MCP server

The same catalogues as an MCP server, for AI assistants and agents: https://michaelghelfistudios.com/api/v1/mcp (Streamable HTTP, stateless, no key, read-only). Tools: search_encyclopedia, get_entry, list_entries, random_entry, list_facets, craft_rules, search_tracks, random_track, get_track, list_composers, list_albums, audio_taxonomy. Every result carries the entries' url and the server's instructions ask the assistant to cite it.

Claude Code:

claude mcp add --transport http mgs-toolbox https://michaelghelfistudios.com/api/v1/mcp

Claude Desktop, Cursor, VS Code, Windsurf and most clients accept a remote server by URL in their MCP settings; the JSON form is:

{
  "mcpServers": {
    "mgs-toolbox": { "type": "http", "url": "https://michaelghelfistudios.com/api/v1/mcp" }
  }
}

Clients that only speak stdio can bridge it with npx mcp-remote https://michaelghelfistudios.com/api/v1/mcp. The server is listed in the official MCP Registry as com.michaelghelfistudios/toolbox. Same rate limit and terms as the JSON API.

Your own data

Your Fantasy City Simulator settlements and Crafting Table campaigns, from your own tools: a Discord bot that posts the settlement's food and gold, a wiki page that lists its inhabitants, a script that exports a party's inventory. Read-only, under a personal API key you create in the hub (menu → API keys) and can revoke any time.

Send it as a bearer token on the /me routes and nowhere else — it is not accepted anywhere else:

curl -H "Authorization: Bearer mgsk_…" "https://michaelghelfistudios.com/api/v1/me/settlements"
curl -H "Authorization: Bearer mgsk_…" "https://michaelghelfistudios.com/api/v1/me/settlements/42/inhabitants?lang=fr"

A key carries the scopes you pick at creation: profile (who you are), fcs:read (settlements, dashboard, inhabitants, campaigns), craft:read (the Crafting Table campaigns you run and their inventories; Patreon, as on the site). Everything is read-only.

There is no audio on this surface, by design: a key never lists entitlements, never downloads, never streams. What you can do with the music catalogue is what the public endpoints offer to everyone.

Keys are stored hashed, look like mgsk_… so secret scanners recognise them, count against the same rate limit as the public API, and show their last use in the hub. Lose one? Revoke it and make another.

Endpoints

Generated from the OpenAPI description. The reference is in English in both languages.

Reference data

Metals, minerals, ingredients, potions, gems and the crafting rules.

Audio catalogue

Tracks, composers, albums, packs and taxonomy of MGS Audio.

Your own data

Read-only access to the account's Fantasy City Simulator and Crafting Table data, with a personal API key (Authorization: Bearer mgsk_…). No audio here, by design.

Embeds

oEmbed and cards.

Meta

Index and documents.

Terms

MGS Toolbox open data terms. Short version: use it, link back, don't clone the site, don't redistribute music.

Free to use

Personal, community and commercial tools alike: Discord bots, VTT modules, note-taking plugins, wikis, generators, your own website. No key, no sign-up, no fee.

Link back

Wherever you show an entry, show where it comes from: the url field of every item is the page to link. A short mention of Michael Ghelfi Studios is enough when a link is impossible (a chat message, a voice assistant).

No mirrors

Do not republish the catalogues as standalone browsable pages that replace the encyclopedias (a copy of every metal, mineral or ingredient with its full text). Quoting entries inside your own content, tools and games is what the API is for; cloning the site is not.

Music stays licensed

The audio endpoints describe the catalogue: titles, composers, moods, pages, embeddable players. They never deliver audio files, and listing a track does not grant any right to the recording. Licences for the music itself are sold on the site.

Be reasonable

Cache responses (they carry Cache-Control), identify your project in the User-Agent header, and stay under the published rate limit. Abusive traffic gets blocked, not throttled.

No warranty, no lock-in

The data is offered as is and may change as the encyclopedias grow. Breaking changes will get a new version prefix; v1 stays up for at least a year after a v2 exists.

Attribution line: Data © Michael Ghelfi Studios — https://michaelghelfistudios.com

Versioning and contact

This is v1. Fields may be added at any time; nothing is removed or renamed without a new prefix. The index lists the current catalogue sizes. Questions, a project to show, a need for a higher limit: michaelghelfistudios.com.