DC Official Clients

Official clients for the Dynamite Circle Member API — your own profile, trips, events, virtual events, tickets, invites, inbox, rooms, chapters, places lookup, and the weekly locator digest.

The Python client is a single self-contained file. Zero dependencies (stdlib only). Works as a CLI, a Python library, and a Model Context Protocol server. Compatible with Claude Code, Claude Desktop, Codex CLI, Gemini CLI, Cursor, GitHub Copilot, and every other Agent Skills / MCP-compatible tool.

The TypeScript client is an npm library for trusted server-side TypeScript projects. It is not a CLI and not an MCP server.

py/dc.py       ← Python: CLI + library + MCP server
ts/src/        ← TypeScript: npm library
contracts/     ← pinned OpenAPI contract shared by both clients

About the Dynamite Circle

The Dynamite Circle is the place where global founders find their people — a curated, members-only community of location-independent business owners running profitable companies around the world. Founded in 2011 (it started with twenty listeners on a remote tropical island), the DC has grown into a hand-selected network of ~1,500 active founders who meet at vetted in-person events like DCBKK and DCMEX, swap notes in private rooms, and travel through each other's home cities year-round.

DC is a private community, but it's open to applications from founders running location-independent businesses doing $100k+ in annual revenue. Every application is personally reviewed by a team member within 48 business hours — start an application here if that sounds like you.

Quick Start

Never used Claude Code, Codex, or git? Here's the 5-minute path from zero to "Claude can read my DC profile."

1. Install the basics (one-time)

You need three free things on your computer:

• Python 3.9+ — the language this client is written in. Download here (Mac/Windows/Linux installers; check "Add Python to PATH" on Windows).
• Git — the tool that downloads code from GitHub. Download here.
• An AI assistant — pick one:
  • Claude Code ← recommended — this repo is built around it
  • Codex CLI — works too, slightly different commands
  • Claude Desktop — the chat app, gets you the MCP server but no CLI

If anything during install asks "do you want to add to PATH?" — say yes.

2. Get the code

Open a terminal:

• Mac: Spotlight → "Terminal"
• Windows: Start → "Terminal" (or "PowerShell")
• Linux: you know what to do

Then paste:

git clone https://github.com/dynamitecircle/dc.git
cd dc

You now have a folder called dc with all the code in it.

3. Get your DC API key

In your browser: go to https://dc.dynamitecircle.com, log in, click your profile photo (top-right), and choose DC Member API Key. Copy the long string starting with dk_….

4. Tell the client about your key

Back in your terminal (still inside the dc folder):

python3 py/dc.py setup --api-key dk_paste_your_key_here

5. Try it

Open Claude Code and make sure it's pointed at the dc folder you just downloaded. (Claude usually opens to your last project — if it's somewhere else, click the folder icon and pick dc.)

Then ask:

"Show me my DC profile"

Claude runs the right command and shows you back your profile. A few more to try:

"What's the latest in DC announcements?" "What events am I attending?" "Show me the DCMEX schedule and bookmark anything about marketing" "Who else from my chapter is going to DCBKK?"

You're done. The rest of this README explains what's possible in more detail; py/SKILL.md lists every command Claude can run.

If something didn't work

How it's exposed

The same dc.py file is shipped as four integrations — pick whichever fits how your tool talks to it:

The mcp package is lazy-imported — Agent Skill / CLI / Python-library users never need it.

TypeScript npm library

For TypeScript projects, use the package under ts/:

import { DC } from "@dynamitecircle/dc";

const dc = new DC({ apiKey: process.env.DC_API_KEY! });

const profile = await dc.profile.get();
const trips = await dc.trips.list({ limit: 10 });

Keep dk_... API keys server-side. Do not ship a member API key in browser JavaScript.

Don't want to install anything? Use the hosted MCP

The DC Member API is also a hosted MCP server — a remote endpoint you point your AI app at, with nothing to clone, install, or update:

https://api.dynamitecircle.com/mcp        (Streamable HTTP)

• Claude Code: claude mcp add --transport http dc https://api.dynamitecircle.com/mcp
• Claude (web / Desktop / mobile): Settings → Connectors → Add custom connector → paste the URL → Connect
• VS Code: click the badge above, or code --add-mcp '{"name":"dc","url":"https://api.dynamitecircle.com/mcp"}'
• Cursor: click the badge above, or add a custom MCP connector pointing at the URL
• ChatGPT / any other MCP app: add a custom / remote MCP connector pointing at the URL above

When prompted, sign in with your DC account (one-click OAuth) — or send a dk_ key as Authorization: Bearer. The server is always on the current API version, so there's nothing to keep up to date.

Hosted MCP vs. this client — which do I want?

The rest of this README is about this client. For the hosted MCP, the URL above is all you need.

Features

• Full Member API coverage — read + write across every public endpoint (run python3 py/dc.py help for the live list)
• Setup command — saves your API key to a chmod-600 .env.dc next to the skill
• Self-test command — validates env, network, key shape, and a live /profile call end-to-end
• Cursor pagination — every list-returning command uses the same [--limit N] [--cursor TOKEN] shape and returns the canonical envelope {items, count, cursor, has_more}
• Three output formats — text (default, pretty JSON), --json, --python
• MCP-ready — same skill auto-exposes all commands as MCP tools
• Pre-configured for Claude Code — repo ships an .mcp.json, just cd and claude

CLI quickstart (already comfortable in a terminal?)

If you're skipping past the Quick Start above and just want the CLI flow, here's the condensed version.

1. Get an API key

DC profile dropdown → DC Member API Key (admins/testers only). Keys look like dk_<api-key> and are revocable from the same dropdown.

2. Save the key

python3 py/dc.py setup --api-key dk_<api-key>

This writes py/.env.dc (chmod 600, gitignored).

3. Verify the connection

python3 py/dc.py self-test

Expected output:

{
  "ok": true,
  "userID": "<your-id>",
  "displayName": "<Your Name>",
  "checks": [
    { "step": "env",      "ok": true, "message": "DC_API_KEY loaded from ..." },
    { "step": "keyShape", "ok": true, "message": "Key prefix valid (expected userID: <id>)" },
    { "step": "profile",  "ok": true, "message": "connected as userID[<id>] <Your Name>" }
  ]
}

4. Try a few commands

python3 py/dc.py profile
python3 py/dc.py trips --limit 5
python3 py/dc.py events --past --limit 3
python3 py/dc.py chapters --limit 5
python3 py/dc.py permacode

Run python3 py/dc.py help for the full command list.

Setup per AI tool

Hosted MCP (no install, always current)

Nothing to clone or update — point your tool at the remote endpoint:

# Claude Code
claude mcp add --transport http dc https://api.dynamitecircle.com/mcp

For Claude web / Desktop, Cursor, ChatGPT, and other MCP apps, add a custom / remote connector pointing at https://api.dynamitecircle.com/mcp (Streamable HTTP). Sign in with your DC account (OAuth) or send a dk_ key as a Bearer header. Discovery is published at /.well-known/mcp.json. This is the lowest-effort path; everything below runs the client locally instead.

Claude Code (local client)

.mcp.json is already shipped with this repo. Open the repo with claude:

cd dc
claude

Tools become available as mcp__dc__*. First-time install of the optional MCP dependency:

pip install -r py/requirements.txt

Skill discovery (CLI + import) works automatically via py/SKILL.md.

Auto-updating local MCP via uvx (PyPI)

Prefer a local stdio server that pulls the latest published client on every launch with no clone to maintain? Use uv's uvx and pass your key in the env block:

{
  "mcpServers": {
    "dc": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--refresh", "--from", "dynamitecircle[mcp]", "dc", "--mcp"],
      "env": { "DC_API_KEY": "dk_<api-key>" }
    }
  }
}

Notes: the console script is dc (not dynamitecircle), so --from dynamitecircle[mcp] is required — it both names the package and pulls the optional mcp extra. --refresh is what makes it auto-update; drop it to let uvx cache. The DC_API_KEY in env wins over any .env.dc (an ephemeral uvx install has none).

Claude Desktop

Easiest — one-click .mcpb: download dc.mcpb from the latest GitHub release and double-click it. Claude Desktop installs the dc server and prompts for your DC_API_KEY (no JSON editing). Requires Python 3.9+ with the mcp package available on your machine (pip install 'dynamitecircle[mcp]'). (Or skip local install entirely and use the hosted MCP connector above.)

Manual — edit your config file:

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

{
  "mcpServers": {
    "dc": {
      "command": "python3",
      "args": ["/absolute/path/to/dc/py/dc.py", "--mcp"]
    }
  }
}

Restart Claude Desktop.

Codex CLI

Edit ~/.codex/config.toml:

[mcp_servers.dc]
command = "python3"
args = ["/absolute/path/to/dc/py/dc.py", "--mcp"]

Codex auto-discovers AGENTS.md (symlinked to CLAUDE.md) and .agents/skills/ (symlinked to .claude/skills/).

Gemini CLI

Reads GEMINI.md (symlinked to CLAUDE.md) for context. For MCP, configure in your Gemini CLI settings:

mcp_servers:
  dc:
    command: python3
    args:
      - /absolute/path/to/dc/py/dc.py
      - --mcp

Cursor

Settings → MCP → Add server, then point at the same dc.py --mcp.

GitHub Copilot

Reads .github/copilot-instructions.md for context. Copilot doesn't have native MCP support yet — use it for in-editor suggestions while developing.

Any other MCP client

Same recipe: command = python3, args = ["/path/to/dc.py", "--mcp"]. The protocol is standard.

Output formats

python3 dc.py profile             # text (pretty JSON for dicts/lists)
python3 dc.py profile --json      # explicit JSON
python3 dc.py profile --python    # Python repr (eval-safe)

Global flags work before or after the command name:

python3 dc.py --json profile
python3 dc.py profile --json

Cursor pagination

All list-returning commands take the same flags:

python3 dc.py trips
python3 dc.py trips --limit 10
python3 dc.py trips --limit 10 --cursor <opaque-token-from-previous-response>
python3 dc.py trips --past --limit 5

Standard envelope:

{
  "items":    [ /* page of records */ ],
  "count":    42,
  "cursor":   "opaque-token-or-null",
  "has_more": true
}

Non-paginated extras (e.g. totalUnread on inbox) are passed through under an extra key.

Use as a Python library

Installed from PyPI (pip install dynamitecircle) — import by the package name:

from dynamitecircle import DC

dc = DC()

Working from a clone instead? Point sys.path at the py/ folder and import as dc:

import sys
sys.path.insert(0, "py")
from dc import DC

dc = DC()

# Reads
profile  = dc.profile()
trips    = dc.trips(past=True, limit=10)
events   = dc.events(past=True, limit=5)
chapters = dc.chapters()
overlaps = dc.overlaps()
locator  = dc.locator(sections="homeCity,favoriteCities")

# Writes
dc.profile_update({"headline": "CEO at Acme"})
dc.trip_create(start_date="2026-12-01", end_date="2026-12-05", place_id="ChIJ...")
dc.event_rsvp("<eventID>", "yes")
dc.invite_create(email="new@friend.com", full_name="New Friend")

Override the API URL (e.g. for a local dev server):

dc = DC(api_url="http://localhost:8080")

API reference

The full live reference for the DC Member API — every endpoint, parameter, and response shape — is at https://www.dynamitecircle.com/developers/. The page is regenerated on every deploy, so it's always current.

Staying up to date

The DC Member API ships new endpoints and refinements regularly. This skill is the official client and we update it whenever the API changes. Plan for updates — the skill will warn you on stderr the first time a request returns an X-API-Version newer than DC_API_VERSION, and major-version bumps may break older clients.

The no-maintenance option: if you use the hosted MCP (https://api.dynamitecircle.com/mcp), there's nothing to update — the server always runs the current API version. The strategies below apply only to the local client.

Pick whichever integration style fits your project. From simplest to most isolated:

0. PyPI — pip / uvx

pip install dynamitecircle              # CLI + library
pip install 'dynamitecircle[mcp]'       # + local MCP server (dc --mcp)

Then dc setup --api-key dk_<api-key> and dc self-test. Update with pip install --upgrade dynamitecircle. For a local MCP that auto-updates on every launch, use the uvx config above.

Best for: the quickest local install, and the auto-updating uvx MCP setup.

1. Plain git clone — quick local use

git clone https://github.com/dynamitecircle/dc.git
cd dc
python3 py/dc.py setup --api-key dk_<api-key>

To update: cd dc && git pull. Run self-test afterwards.

Best for: trying things out, scripts you run by hand, no other repo involved.

2. Git submodule — pinned to a specific commit

If you have your own project repo and want the dc repo versioned alongside it:

cd your-project
git submodule add https://github.com/dynamitecircle/dc.git vendor/dc
git commit -m "Add dc client as submodule"

To update later:

cd vendor/dc
git pull origin main
cd ../..
git add vendor/dc
git commit -m "Bump dc client"

Then in your code:

import sys
sys.path.insert(0, "vendor/dc/py")
from dc import DC

Best for: production-ish code where you want explicit, reviewable bumps.

3. Git subtree — same updates, no submodule indirection

cd your-project
git subtree add --prefix vendor/dc \
  https://github.com/dynamitecircle/dc.git main --squash

Update with:

git subtree pull --prefix vendor/dc \
  https://github.com/dynamitecircle/dc.git main --squash

Best for: teammates who don't know submodules — files just appear in your repo.

4. Symlink — share one clone across many projects

If you keep all your projects in ~/code/:

git clone https://github.com/dynamitecircle/dc.git ~/code/dc

# In each project that uses it:
cd ~/code/your-project
ln -s ../dc vendor/dc

Now cd ~/code/dc && git pull updates every consumer at once. Project-level .mcp.json / .codex/config.toml entries can use vendor/dc/py/dc.py and they'll resolve through the symlink.

Best for: power users with multiple personal projects and one machine.

5. Pip-installable Git ref — one-shot for a virtualenv

The skill is one file with no setup.py, but you can install the package the MCP server needs and check the file out as a sibling:

pip install mcp
git clone https://github.com/dynamitecircle/dc.git

Best for: CI environments, ephemeral containers, scripted setups.

Update etiquette

• Stay current. The DC Member API ships new endpoints regularly and the client mirrors them; running stale means missing features and (eventually) compatibility warnings on stderr.
• Run self-test after every update. Five seconds, catches breakage.
• Watch stderr the first time you call any command after updating. The version-mismatch warning prints once per process when the API is on a newer minor/major.
• Major version bumps may be backwards-incompatible. Read the release notes on the GitHub repo before pulling across a major boundary.

Rate limits

Headers on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Daily-Remaining.

Platform support

Tested on macOS, Linux, and Windows 10/11. Python 3.9+ required (uses pathlib, Path.replace, inspect.signature, contextvars, urllib).

Windows notes

• The skill auto-reconfigures stdout and stderr to UTF-8 at startup, so emoji and em-dashes render correctly even on legacy cmd.exe (which defaults to cp1252). If you still see mojibake on a very old terminal, set PYTHONIOENCODING=utf-8 once: setx PYTHONIOENCODING utf-8 then restart your shell.
• setup writes .env.dc and tries to chmod 600 it. On Windows this is a no-op — the file inherits NTFS perms from its parent. The skill emits a one-time note about this when you run setup. Make sure your repo isn't on a shared drive.
• Use python or python3.exe to invoke; the #!/usr/bin/env python3 shebang is ignored on Windows.

Project layout

dc/
├── README.md                          # this file
├── CLAUDE.md                          # AI-tool guide (also linked as AGENTS.md, GEMINI.md)
├── AGENTS.md       → CLAUDE.md        # symlink (Codex)
├── GEMINI.md       → CLAUDE.md        # symlink (Gemini)
├── LICENSE                            # MIT
├── manifest.json                      # MCPB manifest (MCP 2025-11 spec)
├── .mcp.json                          # auto-registers `dc` MCP server in Claude Code
├── .codex/
│   └── config.toml                    # auto-registers `dc` for Codex CLI
├── .github/
│   └── copilot-instructions.md        # GitHub Copilot
│
├── py/                                # ← Python client (canonical)
│   ├── SKILL.md                       # Agent Skills frontmatter + usage
│   ├── config.json                    # name, version, env requirements
│   ├── dc.py                          # CLI + Python import + --mcp server
│   ├── requirements.txt               # optional MCP dep — skip for CLI/import
│   ├── .env.dc.example                # template
│   └── .env.dc                        # gitignored (created by `setup`)
│
├── ts/                                # ← TypeScript npm library (@dynamitecircle/dc)
│   ├── src/                           # hand-written SDK surface
│   ├── tests/                         # contract + request behavior tests
│   ├── examples/                      # TypeScript usage examples
│   ├── package.json
│   └── tsconfig.json
│
├── contracts/                         # pinned API contract shared by clients
│   ├── openapi.json                   # committed snapshot of /openapi.json
│   └── operation-map.json             # OpenAPI op → Python command → TS method
│
├── DC/
│   └── SKILL.md     → ../py/SKILL.md  # human-friendly skill path (symlink)
│
├── docs/                              # ← REAL design docs (canonical)
│   ├── skill-info.md                # design rules / architecture
│   └── mcp-info.md                    # MCP setup for every supported client
│
├── .claude/                           # Agent Skills discovery (Claude Code)
│   ├── skills/dc  → ../../py          # symlink to canonical Python client
│   └── docs       → ../docs           # symlink to canonical docs
│
├── .agents/                           # Agent Skills discovery (Codex CLI + Gemini CLI alias)
│   ├── skills/dc  → ../../py          # symlink to canonical Python client
│   └── docs       → ../docs           # symlink to canonical docs
│
├── .gemini/                           # Gemini CLI MCP config
│   └── settings.json                  # auto-approves dc MCP tools (trust: true)
│
├── .gitignore
└── .gitattributes

About the layout

This is a monorepo. The Python client lives at /py/; the TypeScript client lives at /ts/. Both wrap the same DC Member API and are validated against the pinned contract in /contracts/. /docs/ is shared. The dotfile-prefixed directories (.claude/, .agents/, .gemini/) exist because AI tools auto-discover skills from those specific paths — they're kept hidden but each one symlinks (or points) straight to the canonical folder, so you only edit files in one place. Edit py/dc.py and Claude Code, Codex, and Gemini CLI all see the same file via their respective discovery directories. Gemini CLI also reads .agents/skills/ as an alias, so we don't need a redundant .gemini/skills/ symlink.

If you're adding Python code or skill docs, edit py/ (or docs/) directly. If you're adding TypeScript library code, edit ts/. The discovery folders take care of themselves.

Pre-approval out of the box

.claude/settings.json, .codex/config.toml, and .gemini/settings.json all auto-approve the dc MCP server's tools so users don't get a per-call approval prompt when they open this repo with their AI tool. Anyone uncomfortable with that can override with their personal .claude/settings.local.json, ~/.codex/config.toml, or ~/.gemini/settings.json. Every dc write tool is scoped to the caller's own DC account via their personal API key — pre-approval doesn't widen any blast radius, just removes per-call friction.

Maintenance

This repo is maintained by the Dynamite Circle team. It's read-only for the public — clone it and use it, but don't open PRs. If you spot a bug or want a new feature, contact us through the official DC channels.

License

MIT — see the LICENSE file for the full text.