Multi-Instance Setup

You can run multiple MCP server instances simultaneously, each pointing to a different Firebase project. This is useful when you manage separate Planning Game deployments — for example, one for your team and another for personal projects.

Why Multi-Instance?

Work + Personal: Keep company tasks separate from side projects
Multiple teams: Each team has its own Firebase project and Planning Game
Staging + Production: Test MCP changes against a staging environment before production

Directory Structure

Create one directory per instance, each containing its own credentials:

~/pg-instances/
  team-a/
    serviceAccountKey.json
    pg.config.yml          # generated by init
    mcp.user.json          # generated by init
  team-b/
    serviceAccountKey.json
    pg.config.yml
    mcp.user.json

Setup Each Instance

Run the init wizard once per instance, from inside each directory:

cd ~/pg-instances/team-a
npx planning-game-mcp init
# Choose instance name: team-a
# Point to ./serviceAccountKey.json
# Complete the wizard

cd ~/pg-instances/team-b
npx planning-game-mcp init
# Choose instance name: team-b
# Point to ./serviceAccountKey.json
# Complete the wizard

The wizard registers each instance in Claude Code automatically. If you prefer manual registration:

claude mcp add planning-game-team-a \
  -e MCP_INSTANCE_DIR=$HOME/pg-instances/team-a \
  -e GOOGLE_APPLICATION_CREDENTIALS=$HOME/pg-instances/team-a/serviceAccountKey.json \
  -s user \
  -- planning-game-mcp

claude mcp add planning-game-team-b \
  -e MCP_INSTANCE_DIR=$HOME/pg-instances/team-b \
  -e GOOGLE_APPLICATION_CREDENTIALS=$HOME/pg-instances/team-b/serviceAccountKey.json \
  -s user \
  -- planning-game-mcp

How `MCP_INSTANCE_DIR` Works

The MCP_INSTANCE_DIR environment variable tells the MCP server where to find its configuration files. When set, the server looks for pg.config.yml, serviceAccountKey.json, and mcp.user.json in that directory instead of the current working directory.

Without MCP_INSTANCE_DIR, the server uses the directory where it was launched.

Identifying Instances

Each MCP response includes an _instance metadata object with the Firebase project ID and instance name. You can also call get_mcp_status on any instance to see:

{
  "firebaseProjectId": "my-team-a-project",
  "instanceName": "team-a",
  "version": "1.16.0",
  "status": "connected"
}

Example: Two Instances in Practice

Suppose you have:

team-a: Your company’s Planning Game (firebase-project-alpha)
team-b: Your personal Planning Game (firebase-project-beta)

After setup, both appear as separate MCP servers in Claude Code. You can then:

# List tasks from team-a
list_cards(projectId="MyCompanyApp", type="task")  → uses planning-game-team-a

# Create a bug in team-b
create_card(projectId="SideProject", type="bug", ...)  → uses planning-game-team-b

The AI agent sees both instances and can route commands to the correct one based on the project context.

Configuration Files Per Instance

Each instance directory contains:

File	Purpose
`serviceAccountKey.json`	Firebase credentials (never commit)
`pg.config.yml`	Instance configuration (name, database URL, user identity)
`mcp.user.json`	User identity for backward compatibility

Updating Instances

To update the MCP server across all instances:

npm update -g planning-game-mcp

All instances use the same binary — only the configuration differs.