Codex is the ChatGPT route into Foundry VTT.

Why the route runs through Codex

Codex is the piece that speaks MCP, so the wire runs Codex to Familiar to your game, and the chat window you normally type into is not on it. Familiar holds the Foundry end: your scenes, sheets and journals for Codex to read, and the tools to change them while the session is running.

The account does not change. You sign in to Codex with the ChatGPT login you already use, so there is no second product to sign up for and no key to buy on this route.

Codex is a developer tool and you are pointing it at a game. It comes as a terminal command or as a tab in the ChatGPT desktop app rather than the chat window you know, and it is the door OpenAI opens for this.

• Install Familiar in FoundryCodex has nothing to talk to until the module is enabled in the world you run.
• Codex CLI and the ChatGPT desktop app: the setup stepsWhere the finished command comes from, and the usual reasons a link never lands.

Wiring Codex to your Foundry game

Codex itself is the one install to do first, as the CLI or as the tab already sitting in the ChatGPT desktop app, and either runs on any ChatGPT plan, Free included. The CLI comes from npm on Node 20 or later, and running codex once walks you through signing in with your ChatGPT account. Until that is done, there is nothing for Familiar to attach to.

Then four steps, and the wizard in Familiar's MCP tab hands you the finished command.

1. 1

   Have Familiar listening

   Familiar installed and enabled in the world you run as GM, with its MCP setup tab open in Foundry. That tab is where the finished command comes from, and where you watch the connection land.

2. 2

   Add Familiar to Codex

   On the CLI that is the single command below. In the desktop app you fill in its own add-server form, and the wizard card lists the command and its arguments as separate values, because that form does not split a pasted line. Take the values the wizard generated either way: they carry the real secret, and on Windows npx becomes npx.cmd. The wizard also hands you a short note for ~/.codex/AGENTS.md; paste that in too, or a fresh conversation will not know Familiar exists. On the CLI you can hand the whole step over instead: that card carries a Copy setup prompt button, and the desktop form does not.

3. 3

   Authorise, then ask it something

   Approve the connection, then send it the verify line from the section below. If nothing comes back in your Foundry window, the fault is in the config rather than in Foundry.

4. 4

   Import the module it will run

   A signed-in agent with a live connection still has nothing to run. Import the published adventure first, so your world holds its journals, sheets and statblocks; hand Codex a chapter out of that and it referees and voices that chapter. It has no story of its own to fall back on.

Codex CLI, the ChatGPT desktop app and the Codex IDE extension all read the same file, ~/.codex/config.toml, so setting Familiar up once covers every Codex surface. The desktop app only reads it at startup: quit it fully, reopen, then check Settings, Plugins, MCPs.

codex mcp add familiar --env FAMILIAR_WS_SECRET=<your-secret> -- npx -y familiar-vtt

• Three ways through the setupFollow the card yourself, have an AI talk you through it, or let the app do the registering.
• Getting a published adventure into FoundryWhat to import, and how to lay it out so an assistant can read it.
• How to play D&D with AIPrep, read, run: the loop that starts with your first imported chapter.

What to type first

With Familiar enabled and Codex signed in, keep the first ask small. The verify line below is the smallest one there is, the same one the wizard's card sends you off with: if Codex names your world back, the wiring holds. Then work up.

• The verify ask

  Use Familiar's get-world-info tool

  Copy The verify ask
• Read the scene

  Read the scene I have open and tell me who is standing in it.

  Copy Read the scene
• Roll a check

  Roll a stealth check for <character> against DC 15.

  Copy Roll a check
• Find a name in your journals

  Search my journals for <NPC name> and give me the passages that mention them.

  Copy Find a name in your journals
• Run a monster's turn

  It's <monster>'s turn. Take it and tell me what it did.

  Copy Run a monster's turn

The game happens in Foundry, not in Codex

Ask for a scene change, a token move or a line spoken aloud, and it happens in the Foundry tab in your browser. What comes back to Codex is a short line of text saying so. Your table sees the change; the terminal sees the receipt.

Pictures are the exception. A generated image returns inline, and so does a screenshot of the live battlemap, an annotated frame with numbered badges on the tokens and a legend naming each one. Codex CLI reasons over that picture without ever showing it to you, because a terminal cannot draw it. The desktop app can.

A few conveniences in Familiar's own chat window never reach an MCP client at all, whichever client it is. The list is short, and worth reading before you go hunting for one of them mid-session.

• Scenes & Tokens
• Voice & Image Generation

• What stays in the Foundry windowThe conveniences that live in the built-in chat only, listed in full.

When Codex says no

None of these need a reinstall. Each one is particular to Codex, which is why the fix is rarely where you would look first. The failures every client shares live on the connect guide, linked below.

• /mcp lists familiar with no tools under it

  A display quirk, not a dead link. Codex keeps MCP tools behind its own tool search, so nothing loads until something calls one. Ask it to use a Familiar tool and watch your Foundry window instead; the list is not the test.

• It opens a browser, or says it has no Foundry tools

  The note for AGENTS.md is missing, or this conversation started before you saved it. Codex does not announce its tools to the model, so it has to be told in that file. Paste it from the wizard card, then start a new conversation: Codex reads the file at the start of one and never again.

• The first run times out

  That first start downloads the helper program, and Codex waits only a few seconds. Get the download out of the way: run npx -y familiar-vtt once in a terminal and let it finish, where a complaint about the secret is the expected ending rather than a fault. Or raise the wait with startup_timeout_sec = 60 under [mcp_servers.familiar] in config.toml, which is the one setting the desktop form has no field for.

• The desktop app shows the server as failed after you save

  Saving does not start it. The form has no restart button, so the server is only picked up on the next launch, and if it still reads failed after you have quit and reopened, do that once more with a minute in between.

• It worked in one window, then not in the next

  Normal, and nothing is broken. Every thread starts its own copy of the helper, and they share one port: the first copy holds it and the rest attach to that one as peers, so each thread still reaches your game. If a thread does come up without them, start a new conversation, give it a few seconds, and ask for a Familiar tool by name rather than asking whether it is connected.

• Nothing you type reaches Foundry at all

  Check which surface you are typing in. The Chat tab, ChatGPT Classic and a Codex session running in the cloud all run on OpenAI's machines, and none of them can reach a program on yours. Use the Codex side of the desktop app, or the terminal.

• The failures every MCP client sharesSafari and the browser choice, an antivirus in the way, a hosted game, and "Not running" while your app says connected.

Once it answers from your world

That is the setup done. What follows is about the game you run with it.

• The rules I give my AI DMA copy-paste pack to hand your assistant at the top of a session.
• How a fight gets refereed once the AI is drivingA live transcript, including the moves the engine refused.
• Playing something other than D&D 5e?A page for each game system covered so far.
• Still nothing landing in Foundry? Ask in the Discord