Connect an External Assistant

Use this guide when you want your own assistant, such as Codex, Claude, Cursor, Windsurf, VS Code, Gemini CLI, or another MCP-compatible client, to work with your TheoryCraft account.

Before You Start

Open the TheoryCraft workspace you want the assistant to use, then go to Settings -> Developer.

Copy the MCP endpoint shown there. The examples below use:

https://beta.theorycraft-trading.ai/mcp

If your settings page shows a different endpoint, use the one from your settings page instead.

If you want the assistant to interact with your current TheoryCraft session, keep TheoryCraft open in your browser.

Choose Access

TheoryCraft supports two connection methods:

Method	Best for
Sign in with TheoryCraft	Clients that open a browser login flow, such as Claude.ai connectors or Codex OAuth login.
Personal token	Clients that ask you to paste a token or read one from an environment variable.

When creating a personal token, choose the smallest access level that fits your use:

Access	Allows
Read only	The assistant can read information from your TheoryCraft account.
Read/write	The assistant can also perform actions in TheoryCraft when you ask it to.

Install TheoryCraft Skills

Install the TheoryCraft skills bundle so your assistant understands TheoryCraft workflows and terminology. Install it once for each client or machine where you use the assistant.

Bundle URL:

https://beta.theorycraft-trading.ai/mcp/skills/theorycraft-skills.zip

Codex

macOS and Linux:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
curl -fsSL https://beta.theorycraft-trading.ai/mcp/skills/theorycraft-skills.zip -o /tmp/tc-skills.zip
unzip -o /tmp/tc-skills.zip -d "${CODEX_HOME:-$HOME/.codex}/skills"
rm -f /tmp/tc-skills.zip

Windows PowerShell:

$dest = "$env:USERPROFILE\.codex\skills"
New-Item -ItemType Directory -Force $dest
Invoke-WebRequest "https://beta.theorycraft-trading.ai/mcp/skills/theorycraft-skills.zip" -OutFile "$env:TEMP\tc-skills.zip"
Expand-Archive -Force "$env:TEMP\tc-skills.zip" $dest
Remove-Item -Force "$env:TEMP\tc-skills.zip"

Claude Code

Claude Code supports personal skills in ~/.claude/skills and project skills in .claude/skills. Use personal skills when you want TheoryCraft available in every project.

macOS and Linux:

mkdir -p "$HOME/.claude/skills"
curl -fsSL https://beta.theorycraft-trading.ai/mcp/skills/theorycraft-skills.zip -o /tmp/tc-skills.zip
unzip -o /tmp/tc-skills.zip -d "$HOME/.claude/skills"
rm -f /tmp/tc-skills.zip

Windows PowerShell:

$dest = "$env:USERPROFILE\.claude\skills"
New-Item -ItemType Directory -Force $dest
Invoke-WebRequest "https://beta.theorycraft-trading.ai/mcp/skills/theorycraft-skills.zip" -OutFile "$env:TEMP\tc-skills.zip"
Expand-Archive -Force "$env:TEMP\tc-skills.zip" $dest
Remove-Item -Force "$env:TEMP\tc-skills.zip"

For project-scoped skills, extract the ZIP into .claude/skills in the project root instead. If Claude Code was already running and the skills directory did not exist yet, restart Claude Code; otherwise it detects changes automatically.

Reference: Claude Code skills.

Claude.ai Skills

Claude.ai manages skills from the Claude settings UI. The TheoryCraft bundle contains multiple skill folders, while Claude.ai uploads expect one skill folder per ZIP. To use the same skills there, download the bundle, extract it, create a separate ZIP for each theorycraft-* folder, then upload those ZIPs from Claude's Skills settings.

If you only need Claude.ai to call TheoryCraft tools, skip the skill upload and use the Claude.ai connector setup below.

Reference: Claude.ai custom skills.

Gemini CLI

Gemini CLI supports Agent Skills in ~/.gemini/skills for user-wide use and .gemini/skills for project-local use.

macOS and Linux:

mkdir -p "$HOME/.gemini/skills"
curl -fsSL https://beta.theorycraft-trading.ai/mcp/skills/theorycraft-skills.zip -o /tmp/tc-skills.zip
unzip -o /tmp/tc-skills.zip -d "$HOME/.gemini/skills"
rm -f /tmp/tc-skills.zip
gemini skills list

Windows PowerShell:

$dest = "$env:USERPROFILE\.gemini\skills"
New-Item -ItemType Directory -Force $dest
Invoke-WebRequest "https://beta.theorycraft-trading.ai/mcp/skills/theorycraft-skills.zip" -OutFile "$env:TEMP\tc-skills.zip"
Expand-Archive -Force "$env:TEMP\tc-skills.zip" $dest
Remove-Item -Force "$env:TEMP\tc-skills.zip"
gemini skills list

Inside an active Gemini CLI session, run /skills reload after installing or updating the bundle.

Reference: Gemini CLI skills commands.

Cursor, Windsurf, VS Code, Continue, and Other Clients

Not every MCP client has a local SKILL.md system. Cursor, Windsurf, VS Code, and Continue primarily document MCP server configuration, so connect them to the TheoryCraft MCP endpoint and let the tool descriptions guide the assistant. If your client later adds first-class SKILL.md support, extract the ZIP into that client's documented skills directory.

Connect Your Client

Codex

Codex with Browser Sign-In

export TC_MCP_URL="https://beta.theorycraft-trading.ai/mcp"
codex mcp add theorycraft --url "$TC_MCP_URL" --oauth-resource "$TC_MCP_URL"
codex mcp login theorycraft --scopes mcp:read,mcp:write

Codex with a Personal Token

Create a personal token in Settings -> Developer, then store it in an environment variable.

macOS and Linux:

export TC_MCP_URL="https://beta.theorycraft-trading.ai/mcp"
export THEORYCRAFT_MCP_TOKEN="paste-your-token"
codex mcp add theorycraft --url "$TC_MCP_URL" --bearer-token-env-var THEORYCRAFT_MCP_TOKEN

Windows PowerShell:

$env:TC_MCP_URL = "https://beta.theorycraft-trading.ai/mcp"
setx THEORYCRAFT_MCP_TOKEN "paste-your-token"
codex mcp add theorycraft --url $env:TC_MCP_URL --bearer-token-env-var THEORYCRAFT_MCP_TOKEN

Restart the terminal after setx so the new environment variable is available.

Claude Code

Claude Code with Browser Sign-In

Add the remote HTTP MCP server, then run /mcp inside Claude Code to complete the browser login flow.

export TC_MCP_URL="https://beta.theorycraft-trading.ai/mcp"
claude mcp add --transport http --scope user theorycraft "$TC_MCP_URL"
claude

In Claude Code:

/mcp

Claude Code with a Personal Token

Create a personal token in Settings -> Developer, then pass it as an HTTP authorization header.

export THEORYCRAFT_MCP_TOKEN="paste-your-token"
claude mcp add --transport http --scope user \
  --header "Authorization: Bearer $THEORYCRAFT_MCP_TOKEN" \
  theorycraft "https://beta.theorycraft-trading.ai/mcp"

Gemini CLI

Gemini CLI with Browser Sign-In

Add TheoryCraft as a user-scoped HTTP MCP server. Gemini CLI opens the browser authentication flow when the server asks for OAuth.

export TC_MCP_URL="https://beta.theorycraft-trading.ai/mcp"
gemini mcp add --transport http --scope user theorycraft "$TC_MCP_URL"
gemini mcp list

Gemini CLI with a Personal Token

Create a personal token in Settings -> Developer, then pass it as an HTTP authorization header.

export TC_MCP_URL="https://beta.theorycraft-trading.ai/mcp"
export THEORYCRAFT_MCP_TOKEN="paste-your-token"
gemini mcp add --transport http --scope user \
  --header "Authorization: Bearer $THEORYCRAFT_MCP_TOKEN" \
  theorycraft "$TC_MCP_URL"

Claude.ai Connector

Create a custom connector and choose browser sign-in.

Use these values when Claude asks for them:

MCP server URL: <the MCP endpoint shown in Settings -> Developer>
Resource URL: <the same MCP endpoint>
Permissions: read/write if you want Claude to perform actions in TheoryCraft, otherwise read only

Cursor

Add TheoryCraft to .cursor/mcp.json for a project, or to your user MCP configuration if you want it available everywhere.

{
  "mcpServers": {
    "theorycraft": {
      "type": "http",
      "url": "https://beta.theorycraft-trading.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:THEORYCRAFT_MCP_TOKEN}"
      }
    }
  }
}

Reference: Cursor MCP configuration.

Windsurf

Open Windsurf's Cascade MCP raw config and add a remote HTTP server. Windsurf uses serverUrl for remote HTTP MCP entries.

{
  "mcpServers": {
    "theorycraft": {
      "serverUrl": "https://beta.theorycraft-trading.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:THEORYCRAFT_MCP_TOKEN}"
      }
    }
  }
}

Reference: Windsurf Cascade MCP.

VS Code

Use the command palette entry MCP: Open User Configuration or create .vscode/mcp.json in a workspace. VS Code uses a top-level servers object, not mcpServers.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "theorycraft-token",
      "description": "TheoryCraft MCP token",
      "password": true
    }
  ],
  "servers": {
    "theorycraft": {
      "type": "http",
      "url": "https://beta.theorycraft-trading.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${input:theorycraft-token}"
      }
    }
  }
}

Reference: VS Code MCP configuration.

Continue and Other JSON MCP Clients

Use the remote MCP or HTTP MCP setup supported by your client. The labels vary by product, but the values are:

Name: theorycraft
URL: <the MCP endpoint shown in Settings -> Developer>
Sign-in method: browser sign-in, or personal token
Resource URL, if asked: <the same MCP endpoint>

If your client asks for a JSON configuration and supports environment variables, use:

{
  "mcpServers": {
    "theorycraft": {
      "type": "http",
      "url": "https://beta.theorycraft-trading.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${THEORYCRAFT_MCP_TOKEN}"
      }
    }
  }
}

For browser sign-in, leave out the headers block and use the sign-in fields shown by your client.

Keep Access Safe

Create a separate token for each client.
Prefer read-only access unless you want the assistant to perform actions in TheoryCraft.
Add an expiration date for temporary devices.
Revoke unused tokens from Settings -> Developer.
Never paste a personal token into a shared repository, issue, chat transcript, or prompt library.