Argo MCP Server

Connects AI assistants to your Argo campaigns via the Model Context Protocol. Once configured, your AI assistant can read and write campaign lore, look up character details, and interact with Argo data directly from the chat interface.

Supported clients: Claude Code, Claude Desktop, OpenAI Codex, VS Code (1.103+), and any MCP-compatible host.

One-click install

Clicking either button hands a vscode:mcp/install URL to your editor with this config:

{ "type": "http", "url": "https://mcp.argo.games/mcp" }

VS Code stores the entry in your user-level mcp.json, then negotiates OAuth on first connect via Dynamic Client Registration against the Argo authorization server. No tokens are embedded in the URL — VS Code stores the resulting access and refresh tokens in your OS keychain.

Linux / Flatpak / Snap note: If clicking the button doesn't open VS Code, the vscode: URL handler isn't registered. This is common on:

• Flatpak / Snap VS Code — the sandbox isolates the install from the host, so the host browser can't find the protocol handler.
• Tarball / manual installs — no postinst hook runs update-desktop-database. Either run xdg-mime default code.desktop x-scheme-handler/vscode once, or use the manual fallback below.

Manual fallback: copy the JSON from the VS Code (one-click, recommended) section below into your VS Code mcp.json config.

The same install button is rendered on the Argo install page at https://app.argo.games/docs/mcp/install.

Prerequisites

• Node.js 20 or later
• An Argo account with at least one campaign
• A Game Master must authorize the AI assistant via the OAuth2 consent flow (see Getting a token)

Quick start

There are three supported ways to use the Argo MCP server. Pick the one that matches your client.

ChatGPT (remote)

Use the hosted endpoint — do not install the npx package. Add this MCP server URL to ChatGPT:

https://mcp.argo.games/mcp

ChatGPT will walk you through OAuth on first connect via dynamic client registration.

Local MCP clients (Claude Code, Claude Desktop, Codex, etc.) — recommended

Sign in once on the machine that runs the MCP client:

npx -y argo-mcp auth login

The command prints the consent URL, opens nothing, and asks you to paste the access token (and optionally the refresh token) from the consent page. Tokens are saved locally:

• Windows: %APPDATA%\argo-mcp\tokens.json
• macOS: ~/Library/Application Support/argo-mcp/tokens.json
• Linux: ${XDG_CONFIG_HOME:-~/.config}/argo-mcp/tokens.json

Then configure the MCP server with no env vars:

{
  "mcpServers": {
    "argo": { "command": "npx", "args": ["-y", "argo-mcp"] }
  }
}

Other auth commands:

npx -y argo-mcp auth status   # show whether you are signed in
npx -y argo-mcp auth logout   # forget locally stored tokens

Local stdio mode does not use OAuth Dynamic Client Registration. DCR is only used by the hosted HTTP server at https://mcp.argo.games.

Advanced — environment variables

For CI, Docker, or anyone who prefers explicit env config, you can skip auth login and pass tokens directly. OAUTH_TOKEN always wins over the local token store.

{
  "mcpServers": {
    "argo": {
      "command": "npx",
      "args": ["-y", "argo-mcp"],
      "env": {
        "OAUTH_TOKEN": "<your-access-token>",
        "REFRESH_TOKEN": "<your-refresh-token>"
      }
    }
  }
}

Build from source (contributors)

git clone https://github.com/Argo-RPG-Platform/MCP.git argo-mcp
cd argo-mcp
npm install
npm run build

Getting a token

The MCP server authenticates with Argo using an OAuth2 access token tied to a specific set of campaigns. Tokens are obtained through the Argo consent flow:

1. Open https://app.argo.games/oauth2/mcp-connect in your browser.
2. Select the campaigns you want the AI assistant to access and the permission level (read or read+write).
3. Click Authorize. You will be redirected to a page showing two tokens:
   • Access token — set this as OAUTH_TOKEN
   • Refresh token — set this as REFRESH_TOKEN (recommended; enables automatic renewal when the access token expires after ~1 hour)

Treat both tokens like passwords. Revoke them at any time from the campaign's integrations page.

Configuration

VS Code (one-click, recommended)

Use the install buttons at the top of this README, or paste the following into a .vscode/mcp.json (per-workspace) or your user-level MCP config:

{
  "servers": {
    "argo": {
      "type": "http",
      "url": "https://mcp.argo.games/mcp"
    }
  }
}

VS Code handles OAuth automatically via Dynamic Client Registration on first connect. There is no need to set OAUTH_TOKEN or REFRESH_TOKEN — VS Code stores tokens in the OS keychain.

Claude Code

Add the server with the CLI:

claude mcp add argo \
  --command node \
  --args /absolute/path/to/argo-mcp/dist/index.js \
  --env OAUTH_TOKEN=<your-access-token> \
  --env REFRESH_TOKEN=<your-refresh-token>

Or add it manually to your project's .claude/settings.json:

{
  "mcpServers": {
    "argo": {
      "command": "node",
      "args": ["/absolute/path/to/argo-mcp/dist/index.js"],
      "env": {
        "OAUTH_TOKEN": "<your-access-token>",
        "REFRESH_TOKEN": "<your-refresh-token>"
      }
    }
  }
}

Claude Desktop

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "argo": {
      "command": "node",
      "args": ["/absolute/path/to/argo-mcp/dist/index.js"],
      "env": {
        "OAUTH_TOKEN": "<your-access-token>",
        "REFRESH_TOKEN": "<your-refresh-token>"
      }
    }
  }
}

Restart Claude Desktop after saving.

OpenAI Codex

Add the server to your Codex MCP configuration:

{
  "mcpServers": {
    "argo": {
      "command": "node",
      "args": ["/absolute/path/to/argo-mcp/dist/index.js"],
      "env": {
        "OAUTH_TOKEN": "<your-access-token>",
        "REFRESH_TOKEN": "<your-refresh-token>"
      }
    }
  }
}

ChatGPT App Submission

For the hosted ChatGPT app surface, this repo exposes OAuth discovery, dynamic client registration, and domain verification endpoints on the MCP domain. The submission checklist and required env vars are in CHATGPT_APP_SUBMISSION.md.

Using a .env file (local dev)

Create a .env file in the argo-mcp directory:

OAUTH_TOKEN=<your-access-token>
REFRESH_TOKEN=<your-refresh-token>

Then run directly:

npm run dev       # hot-reload via tsx
# or
npm start         # compiled dist/

Pre-built Agent Skills

Once the MCP is connected, you can install the argo-agent-skills plugin to get ready-made Game Master workflows that orchestrate the tools below — session prep, post-session recap, NPC generation, and a guided MCP setup walkthrough. The same skill source ships parallel packaging for Claude (Code + Claude.ai) and OpenAI-compatible clients (Codex, ChatGPT).

Claude Code:

/plugin marketplace add Argo-RPG-Platform/argo-agent-skills
/plugin install argo-gm-pack@argo

Claude.ai / Codex / ChatGPT: download the per-target zip from the latest release and follow the upload steps in that repo's README.

See the Argo Skills docs for the full list of skills, examples, and authoring guidance for your own.

Available tools

This server exposes tools across campaigns, mnemons, sessions, guilds, friends, and the Argo community forum.

Campaigns

• list_campaigns (campaign.read) lists accessible campaigns and their access level
• get_campaign (campaign.read) retrieves campaign details
• create_campaign (campaign.create) creates a new campaign
• update_campaign (campaign.write) updates campaign name or description
• list_co_gms (campaign.read) lists assistant GMs
• add_co_gm (campaign.write) adds an assistant GM
• remove_co_gm (campaign.write) removes an assistant GM

Mnemons

• describe_mnemon_types lists supported mnemon types, relationship labels, and content-block rules
• list_mnemons (campaign.read) lists mnemon entries for a campaign
• get_mnemon (campaign.read) retrieves a mnemon entry in full
• list_mnemon_relationships (campaign.read) lists linked entries and relationship edges
• create_*_mnemons (campaign.write) creates typed mnemon entries for NPC, Location, Quest, Lore, Archive, Journal, SessionSummary, Player, and Custom entries
• update_*_mnemons (campaign.write) updates typed/meta fields for those mnemon entry types
• update_mnemons_content (campaign.write) edits mnemon content blocks
• create_mnemon_relationship (campaign.write) creates a relationship between entries
• delete_mnemon_relationship (campaign.write) deletes a relationship by ID

Sessions