BranchManager69/dexter-mcp

Dexter API · Dexter FE · Dexter MCP · Dexter Ops · PumpStreams

Dexter MCP

Fully managed Model Context Protocol (MCP) bridge for Dexter. The service exposes a curated set of connector tools (wallet resolution, diagnostics, session overrides) over both stdio and HTTPS, reusing the Dexter OAuth infrastructure for user-level access control.

Highlights

• Production-ready HTTP transport – OAuth2/OIDC, bearer fallback, SSE streaming, and metadata endpoints compatible with Claude & ChatGPT connectors.
• Wallet-first toolset – resolve_wallet, list_my_wallets, auth_info, set_session_wallet_override, plus per-session overrides backed by Supabase.
• Composable tool registry – drop new bundles into toolsets/, enable them via env, CLI flags, or ?tools= query parameters.
• Dual-runtime – stdio entrypoint for local agents & Codex, HTTPS entrypoint for public connectors (proxied at https://dexter.cash/mcp and https://mcp.dexter.cash/mcp).
• Supabase-native auth – validates incoming tokens through Dexter API/Supabase resolver, injects identity headers for downstream tools, and preserves token caching to limit IdP calls.

Access Tiers

Guest/demo/member terminology maps to marketing: the shared bearer is a full managed wallet so prospects experience real trades without creating an account, while member-tier tools expect the per-user wallet provisioned at signup.

Dexter Stack

Quick Start

git clone https://github.com/BranchManager69/dexter-mcp.git
cd dexter-mcp
npm install
cp .env.example .env

# populate .env with Supabase + OAuth settings (see Configuration)

# HTTPS transport (port 3930)
npm start

# or stdio transport for local tools
node server.mjs --tools=wallet

Verify the HTTP transport:

curl -sS http://localhost:3930/mcp/health | jq

With the public proxy in place you can also query:

curl -H "Authorization: Bearer <TOKEN_AI_MCP_TOKEN>" \
     https://mcp.dexter.cash/mcp/health

Authentication

Metadata endpoints (for connector discovery) are exposed at:

• /.well-known/oauth-authorization-server
• /.well-known/oauth-protected-resource
• /.well-known/openid-configuration

These routes are proxied on both dexter.cash and mcp.dexter.cash, so connectors can follow the same issuer regardless of which hostname they use.

Toolsets

Tool bundles live under toolsets/<name>/index.mjs and register themselves through the manifest in toolsets/index.mjs.

Currently shipped:

• general – Static search / fetch helpers that surface curated Dexter OAuth + connector docs.
• pumpstream – pumpstream_live_summary wrapper for https://pump.dexter.cash/api/live with paging, search, and filter controls.
• wallet – Supabase-backed wallet resolution, diagnostics, and per-session overrides (used by all Dexter connectors).
• solana – Token resolution, portfolio balances, and managed-wallet buy/sell execution (proxied through dexter-api).

Each tool definition exposes an _meta block so downstream clients can group or gate consistently:

{
  "name": "solana_execute_buy",
  "title": "Execute Buy",
  "description": "Buy a token using SOL from a managed wallet.",
  "_meta": {
    "category": "solana.trading",
    "access": "managed",
    "tags": ["buy", "execution"]
  }
}

• category – high-level grouping for UX (e.g. wallets, analytics, solana.trading).
• access – current entitlement level (public, free, pro, managed, internal).
• tags – free-form labels for filtering/badging.

The /tools API simply relays this metadata so UIs (including dexter-fe) pick it up automatically. Add new values conservatively and document them if third-party clients depend on them.

Selection options:

• Environment default: leave TOKEN_AI_MCP_TOOLSETS unset to load every registered bundle (general,pumpstream,wallet). Set it (comma-separated) to restrict the selection, e.g. TOKEN_AI_MCP_TOOLSETS=wallet.
• CLI/stdio: node server.mjs --tools=wallet.
• HTTP query: POST /mcp?tools=wallet.
• Codex: set TOKEN_AI_MCP_TOOLSETS in the env before launching, or add includeToolsets when invoking buildMcpServer manually.

Legacy Token-AI bundles remain in legacy-tools/ for reference. They are not registered by default but can be migrated into toolsets/ as they are modernized.

Configuration Reference

Populate .env (or inject via process manager) with at least:

StdIO launches also load environment files from the repo root and token-ai/.env, so shared secrets can be stored once and reused across services.

Development & PM2

Run locally:

# HTTP transport with auto-reload (e.g. via nodemon)
TOKEN_AI_MCP_PORT=3930 npm start

# Stdio session for quick manual tests
node server.mjs --tools=wallet

# Connect with Codex (bearer token example)
# ~/.codex/config.toml
# [mcp_servers.dexter]
# transport = "http"
# url = "https://mcp.dexter.cash/mcp"
# headers = { Authorization = "Bearer <TOKEN_AI_MCP_TOKEN>" }

Harness smoke (API default)

The helper script can exercise the new pagination either through the Playwright UI flow or directly via the MCP API:

# API only (default)
npm run test:pumpstream -- --page-size 5 --json --no-artifact

# UI only (optional)
export HARNESS_COOKIE='cf_clearance=...; sb-xyz-auth-token=...; sb-xyz-refresh-token=...'
npm run test:pumpstream -- --mode ui --headful --prompt "List pump streams"

# API only (no browser)
export HARNESS_MCP_TOKEN='Bearer <mcp bearer>'   # if session response redacts the header
export HARNESS_SESSION_URL='https://api.dexter.cash/realtime/sessions'  # optional override
npm run test:pumpstream -- --mode api --page-size 10 --json --no-artifact

The harness auto-loads .env, so you can keep HARNESS_COOKIE, HARNESS_AUTHORIZATION, HARNESS_MCP_TOKEN, and other overrides there instead of exporting them per run (see .env.example). Default mode is API-only; when you explicitly run --mode both, the script still executes API mode even if UI credentials are missing or the Playwright run fails—it logs the UI error and continues.

Flags (--prompt, --url, --wait, --headful, --no-artifact, --json, --mode, --page-size) are forwarded to the underlying runners. UI mode requires a fresh Supabase session (HARNESS_COOKIE or HARNESS_AUTHORIZATION). API mode falls back to guest sessions but can reuse the same cookies/headers to hop past Cloudflare; if the session payload redacts the MCP header, provide HARNESS_MCP_TOKEN (or reuse TOKEN_AI_MCP_TOKEN).

For production, PM2 is managed through dexter-ops/ops/ecosystem.config.cjs. The config already forwards TOKEN_AI_MCP_OAUTH=true and supporting variables; restart via:

pm2 restart dexter-mcp
pm2 logs dexter-mcp

Session Maintenance Cheatsheet

Turnstile + Supabase login (desktop helper)
           │  generates encoded cookie + state.json
           ▼
HARNESS_COOKIE in repos (.env)
           │  injected into Playwright runs
           ▼
Dexchat / pumpstream harness executions

Remember: the desktop helper is rare (weeks between runs). dexchat refresh is the lightweight, local option you’ll use most often. Additional command details live in dexter-agents/scripts/README.md.

Architecture Notes

• common.mjs – builds the MCP server, normalizes Zod schemas, wraps tool registration with logging.
• toolsets/ – declarative manifest of tool bundles plus the wallet toolset implementation.
• Toolset authoring guide: see toolsets/ADDING_TOOLSETS.md for step-by-step instructions and examples (including the pumpstream toolset).
• server.mjs – stdio entrypoint (used by local agents and Codex); respects --tools= flags.
• dexter-mcp-stdio-bridge.mjs – bridges stdio clients to the hosted OAuth HTTP transport (handy for Codex/Cursor when they only support stdio).
• http-server-oauth.mjs – HTTPS transport with OAuth/OIDC, session caching, and metadata routes (still contains a Prisma-backed fallback to seed per-session wallet overrides).
• legacy-tools/ – archived Token-AI tools kept for reference during migration.

Supabase interactions flow through Dexter API helpers for consistent auth enforcement. The only remaining Prisma access is the wallet-override seeding noted above; retire it when the resolver exposes a "default wallet" flag.

Related Repositories

• – OAuth issuer, wallet resolver, and connector orchestration.
• – Web frontend (Claude/ChatGPT connector auth, realtime demos).
• – Monitoring suite that inspired this README structure.

License

Private – internal Dexter connector infrastructure.