Connect Claude, ChatGPT, or Gemini to your Foundry game.

What you need before you connect

The Foundry half is probably already true. The AI half is the part to check.

• Foundry VTT v13 or later, and a world you run as GM, with Familiar installed and enabled in it.
• A desktop AI app that speaks MCP, on a plan that includes it. The table below names every client and what each one needs.
• Node.js 22 or newer, on the computer that runs the AI app. That has to be the computer with your Foundry tab open too: the server your app starts reaches Foundry over the local loopback. On Windows take the current LTS, because the antivirus fix below needs 22.15 or newer.

• Install Familiar in FoundryBoth routes into the Install Module dialog, and the Foundry versions.
• How to add AI to Foundry VTTThe step before this one, and the shorter way in through a provider key.

Which AI assistants can drive Foundry VTT?

Claude, ChatGPT through Codex, Gemini through Antigravity, Grok through Grok Build, and Meta's Muse Code can all drive Foundry. MCP, the Model Context Protocol, is the open standard that lets an AI app reach an outside tool and use it. Familiar is that tool for your Foundry table.

The wizard is in Foundry: Module Settings, Familiar, then the MCP / Subs tab, a card per client grouped by the subscription behind it. Pick yours and it writes the exact text with this world's secret already in it. A config block, one command, or values for a form.

Grok Build imports the MCP servers, skills and hooks of Claude Code and Cursor by default, so anything you set up there turns up in Grok too. Its own entry still wins for familiar, and the card names the settings that keep the rest out.

• Claude in Foundry: Desktop or CodeTwo clients on one Anthropic plan, and how differently you add each one.
• ChatGPT in Foundry via CodexWhich surface of the ChatGPT app is on the wire, and the note Codex needs.
• Gemini in Foundry via AntigravityTwo separate installs on one Google account, and the snags only Antigravity has.
• Grok in Foundry via Grok BuildWhat a terminal changes at the table, and the six snags only Grok Build trips.
• Muse Code in Foundry: one settings fileMeta's terminal agent keeps Familiar and its model in one file: what the wizard card writes there, and the fixes for its installer and settings file.

Where the finished command comes from

Some cards end in a single command, and those are the ones below.

The lines below leave FAMILIAR_WS_SECRET as a placeholder, so copy the real one from your card instead: the wizard mints this world's own secret and fills it in. Every world generates its own. Familiar's WebSocket Secret module setting is how one config comes to serve all of them.

On Windows the wizard adds NODE_USE_SYSTEM_CA=1 to everything it writes, and npx.cmd in place of npx where the client needs it. Run it from a hosted game and your game's URL goes in as FAMILIAR_WS_ALLOWED_ORIGINS on its own.

claude mcp add familiar --scope user --env FAMILIAR_WS_SECRET=<your-secret> -- npx -y familiar-vtt

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

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

Three ways through the setup

Three routes end in the same place, Familiar registered in your AI app, and you only need one. They run from doing all of it yourself to handing the job to the app.

Menu names and field labels move between app versions, so your card in the wizard is the current click-by-click. What stays put is the shape below.

1. 1

   Follow the card yourself

   Each card is written for someone who has never installed a developer tool. Every value is a copy box, an install step ends with what you should see, and the add step says what the command prints, then gives you a check that should name familiar.

2. 2

   Have an AI talk you through it

   Every card carries a Copy help prompt button. Paste that prompt into any AI chat you already use, the free web versions of ChatGPT and Claude included, and it walks you through the same steps with your own values in place. It explains, you type. It never needs access to this computer.

3. 3

   Let the app register Familiar itself

   The Claude Code, Codex CLI and Grok Build cards add a second button, Copy setup prompt. Install the app and sign in first; that part stays yours. Paste the prompt in and it runs the registration, asks your approval as it goes, then verifies. It needs a normal session on your own computer; from a cloud sandbox it stops and points you back to the card.

Check the link before you play

Your card carries two status rows, one for the MCP Server and one for your app, and both read Connected once the link is up. Nothing needs reloading; the tab updates on its own. On a first run both rows can sit on Waiting for a moment.

Then send the two lines below. The first is the wizard's own question. The second is a roll that has to land in your Foundry chat log, which proves the write reaches Foundry and not only the read.

• The wizard's own line

  Use Familiar's get-world-info tool

  Copy The wizard's own line
• A roll that has to land in Foundry

  Roll a d20 and post the result to the Foundry chat.

  Copy A roll that has to land in Foundry

What changes at the table

You talk to your AI app in plain language, the same as always, and it calls Familiar's tools as it goes. Whatever you ask for happens in your Foundry tab: tokens move, conditions apply, the journal opens on the right page. What your client gets back is a line saying so.

• Scenes & Tokens
• Journals & Notes
• Knowledge & Memory

• Staying consistent across sessionsWhat the record holds, and why a client has to ask before it gets any.
• Claude in Foundry: Desktop or CodeDesktop's curated set, and the one line that widens it.
• Everything Familiar can doThe full list behind those rows, laid out by domain.

The failures every MCP client shares

A failure only one client shows lives on that client's page, linked above. These six stop every client.

• Foundry says "MCP Server: Not running" while your AI app says it is connected

  Two different lights. The server row is the helper program, the client row is your app, and both need a moment after the app starts. The very first start also downloads the server, so give it a minute. Still nothing? Click Reconnect under the rows, or reload Foundry.

• A paste that will not take: your app reports an invalid secret, or the connection is refused

  The secret in the config is not this world's. Copy the finished command or block from your card again, which always carries the current value, or set Familiar's WebSocket Secret module setting to the value your config already has. Every world mints its own, and that setting is how one config serves them all.

• On a hosted game nothing connects, and the status row stays on Not running

  Hosted Foundry itself is fine: the server runs on your machine, never on the host. Chrome and Edge ask once whether the page may reach devices on your local network. Allow it. Dismissed it in Chrome? It is back under the site icon at the left of the address bar, Site settings, Local network access, then reload. The status row says so when your browser reports that permission blocked.

• The built-in chat works, but every tool call says it could not confirm an active licence

  An antivirus that inspects HTTPS traffic, AVG and Avast among them, blocks the server's licence check while your browser sails through. The wizard already writes NODE_USE_SYSTEM_CA=1 into every Windows command and config it generates, and that needs Node 22.15 or newer. If you registered Familiar by hand, add it beside the secret and restart your app.

• PowerShell says running scripts is disabled on this system

  Windows blocks npm and npx in PowerShell until you allow it once. Run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser in that same window, answer Y, then run the failed command again. On a managed work computer that setting can be locked, and Command Prompt is the way round it.

• Safari never connects to a hosted game

  Safari does not let a hosted page reach a program on your own machine, which is exactly what this connection is. Use Chrome, Edge or Firefox for a hosted game. A game you run on your own computer is not affected.

• Stuck? Ask in the DiscordThe place to take a symptom that is not on this list.