Connect Your Game Design Docs to Claude Code (Step-by-Step)

Read Time: 8 minutes

§What You'll Set Up#

By the end of this guide, Claude Code will have live, read-only access to every document in your GameFrame vault. That means you can ask questions like "What are the Mage's base stats?" or "What changed in the combat spec last week?" and get answers pulled directly from your versioned design documents --- not from stale context or copy-pasted snippets.

The connection uses the Model Context Protocol (MCP), an open standard that lets AI tools talk to external data sources. GameFrame's MCP server exposes your vaults, documents, entities, and version history as structured tools that Claude Code can call on demand.

No code changes. No SDK. Just a config file and an API token.

§Prerequisites#

Before you start, make sure you have:

• —A GameFrame account with at least one vault containing documents
• —Claude Code installed and working on your machine (installation guide)
• —Node.js 18+ installed (the MCP server runs as a Node process)

§Step 1: Create Your API Token#

1. 1.Log in to GameFrame and open any vault
2. 2.Go to Settings > API Tokens (or visit your account settings)
3. 3.Click Create Token
4. 4.Give it a descriptive name, like claude-code-read
5. 5.Select the read scope --- this gives access to documents, entities, and version history without the ability to modify anything
6. 6.Click Generate and copy the token immediately --- it starts with gf_ak_ and won't be shown again

Store the token somewhere safe. You will paste it into your config file in the next step.

§Step 2: Configure .mcp.json#

Claude Code reads MCP server configurations from a .mcp.json file in your project root. Create or edit this file:

{
  "mcpServers": {
    "gameframe": {
      "command": "npx",
      "args": ["-y", "@gameframe/mcp-server"],
      "env": {
        "GAMEFRAME_API_TOKEN": "gf_ak_your_token_here"
      }
    }
  }
}

What each field does:

• —"command": "npx" --- runs the server package without a global install
• —"args": ["-y", "@gameframe/mcp-server"] --- auto-confirms the download and specifies the package
• —"env" --- passes your API token to the server process as an environment variable

Save the file and restart Claude Code (or open a new session). The MCP server starts automatically when Claude Code detects the config.

§Step 3: Verify the Connection#

Open Claude Code and type:

"List my GameFrame vaults"

Claude Code will call the list_vaults tool and return a list of every vault your token has access to. You should see vault names, IDs, and document counts.

If this works, the connection is live. Every tool the MCP server exposes is now available to Claude Code, and it will call them automatically when your prompts require design document context.

§Step 4: Try These Prompts#

Here are five prompts that demonstrate what you can do with the connection active. Try them with your own vault data:

1. Browse your vault#

"What documents are in my vault?"

Returns every document with its type, path, and last-modified date. Useful for orienting Claude Code to your project structure.

2. Read a full document#

"Read the combat system GDD"

Pulls the latest version of the document and loads it into context. Claude Code can now answer follow-up questions about the content without you pasting anything.

3. Search entities#

"What entities are in character_balance.gsheet?"

Returns extracted entities (characters, stats, items, abilities) from the specified document. This is how Claude Code learns the actual values in your balance data.

4. Check version history#

"What changed in the combat spec since version 5?"

Returns the version log with change prompts, timestamps, and authors. Useful for understanding why a design decision was made.

5. Compare versions#

"Compare the last two versions of progression-curve.gsheet"

Returns a structured diff showing what values changed between versions. Great for reviewing balance changes or catching unintended edits.

§Enabling Write Access#

If you want Claude Code to create documents or upload new versions, generate a second token with the write scope. Replace the token in your .mcp.json or create a separate config for write-enabled sessions.

With write access, three additional tools become available:

• —create_document --- create a new document in a vault
• —upload_version --- upload a new version of an existing document
• —update_document_metadata --- change a document's title, tags, or description

Write operations respect the same permissions as the web UI. If your account does not have write access to a vault, the token will not grant it either.

§Troubleshooting#

"Token not found" or "Unauthorized" errors

• —Double-check that the token in .mcp.json starts with gf_ak_
• —Make sure there are no extra spaces or newline characters in the token string
• —Verify the token has not been revoked in your GameFrame settings

"Rate limited" responses

• —The MCP server respects the same rate limits as the REST API
• —Free-tier accounts are limited to 60 requests per minute
• —If you hit the limit, wait 60 seconds and try again

"Connection error" or server not starting

• —Confirm Node.js 18+ is installed: node --version
• —Try running the server manually: npx @gameframe/mcp-server --- it should print a startup message
• —Check that your firewall or proxy is not blocking outbound HTTPS to api.getgameframe.com

Claude Code does not seem to use the tools

• —Restart Claude Code after editing .mcp.json
• —Check that the file is in the project root, not a subdirectory
• —Ask explicitly: "Use the GameFrame MCP tools to list my vaults"

For the full API reference, tool documentation, and integration guides for other MCP-compatible tools, visit the Developers page.