{
  "markdown": "# GammaRips MCP Server\n\n[![smithery badge](https://smithery.ai/badge/gammarips/Options-Intelligence)](https://smithery.ai/servers/gammarips/Options-Intelligence)\n\nOptions-flow intelligence **primitives** for AI agents.\n\nEvery trading night GammaRips ranks 3,532 optionable US names by liquidity, takes the top 100, keeps the bullish ones, and prices one out-of-the-money call in each. That is a pool of roughly 40 to 50 contracts your agent can actually trade. This MCP server gives a bring-your-own-agent trader that pool plus the substrate to reason over it: point-in-time features, realized **opportunity surfaces** (max-favorable / max-adverse excursions with no exit applied), bracket outcome labels, regime context, and methodology playbooks.\n\n**We do not claim these are the best contracts.** Two pre-registered studies found the pool indistinguishable from matched random optionable contracts. What the liquidity rule measurably fixes is executability: on a 60-day window ending 2026-08-14, no-fill at 10:00 ET went from 40.5% to 6.1%. Those are study numbers, not a live property of the pool.\n\n**Design principle: primitives, never a pick.** There is no \"what should I buy\" endpoint. Every agent reasons from the same data to its *own* contract and its *own* exit. Paper-traded research data; educational only; not investment advice.\n\n## Hosted MCP endpoint\n\n- **Streamable HTTP (primary):** `https://mcp.gammarips.com/mcp`\n- **SSE (legacy, deprecation window):** `https://mcp.gammarips.com/sse`\n- **Stateless JSON-RPC:** `https://mcp.gammarips.com/jsonrpc`\n- **Server card:** `https://mcp.gammarips.com/.well-known/mcp/server-card.json`\n- **OAuth endpoint (chat clients):** `https://mcp.gammarips.com/pro`. Same\n  server, same 9 tools, but it requires a credential, so ChatGPT, Claude\n  (claude.ai / Desktop), Cursor, and any MCP client that speaks OAuth 2.1\n  offers a GammaRips sign-in when you add it. Your subscription tier rides in\n  the token. Discovery: `/.well-known/oauth-protected-resource/pro`;\n  authorization server: `https://gammarips.com`.\n- **Auth:** two credentials, one tiering. (1) API key: `gr_live_...` as\n  `Authorization: Bearer <key>` (or `X-API-Key`), for clients that can send a\n  header. (2) OAuth 2.1 access token, minted by gammarips.com after you sign in\n  (chat clients) or by a machine client with `client_credentials` (headless\n  agents, see below). Free-tier tools work on `/mcp` with no credential at all;\n  the 4 pro tools need an active subscription on either credential. **Enforce**\n  is live. Get access at [gammarips.com/pricing](https://gammarips.com/pricing).\n\n## Available tools (9)\n\nV4 (2026-07-17) consolidated the 29-tool V3 surface into 9. The absorbed tools\nlive on as `view=` / `granularity=` modes of these 9. `web_search` was removed.\n\n**Free tier** (no key): `get_pool`, `get_regime_context`,\n`get_market_calendar_status`, `get_playbook`, `get_daily_report`.\n**Pro tier** (Agent Access, $29/mo key): `get_signal`, `get_liquidity`,\n`query_outcomes`, `replay_contract`.\n\n- `get_pool` **(free)** — the candidate pool: `view=\"enriched\"` (curated\n  narrative/technicals/contract/`mom_60`, leakage-safe view; default),\n  `\"raw\"` (pre-curation scan), `\"features\"` (point-in-time feature vectors\n  from the allowlist view), `\"preview\"` (public teaser).\n- `get_signal` **(pro)** — one ticker: `view=\"detail\"` (full enrichment,\n  default) or `view=\"earnings\"` (the doctrine earnings-window check).\n- `get_liquidity` **(pro)** — fresh entry-day liquidity: a single `contract`\n  (cache-first, `live=true` to force upstream) or the whole pool / a\n  `contracts` shortlist in one call. No quote fields on this data plan.\n- `query_outcomes` **(pro)** — the outcomes + receipts substrate, via `view=`:\n  `labels` (row-level bracket labels + features; default), `summary` (grouped\n  aggregates), `surface` (per-contract MFE/MAE excursions, exit-free —\n  `aggregate_only=True` gives MFE/MAE quantiles over the WHOLE window and is the\n  mode to use for exit design, since row mode is capped at 200 rows and declares\n  it via `truncated` / `matched_rows` / `partial_scan_date`),\n  `harvest` (touch-probability curve), `exit_rule` (score YOUR bracket/trailing\n  rule), `signal_performance` / `win_rate` (UNDERLYING-direction, **not** option\n  PnL), `positions` / `performance` (the engine's realized paper-trade receipts,\n  cohort-filtered). The live cohort is the **pair** `V7_1_TILTED_GIGO` **and**\n  entry on/after `cohort_start` (2026-08-10), which responses now carry — the\n  policy label ALONE does not define the cohort, because the ledger retains\n  disowned cohorts under that same label. Right after a reset the live cohort\n  is legitimately empty: `total_trades: 0` with `null` aggregates means \"has not\n  accrued closed trades yet\", NOT \"0% win rate\". `policy_version=\"all\"` reaches\n  every era but includes cohorts the engine has disowned — not a track record.\n- `replay_contract` **(pro)** — raw price tape for your own exit rule:\n  `granularity=\"minute\"` (intraday path + exact first-crossing; default) or\n  `\"day\"` (daily OHLCV mark series). This server does not simulate exits.\n- `get_regime_context` **(free)** — VIX/VIX3M/SPY-trend as-of scan date + the\n  fail-closed regime rail.\n- `get_market_calendar_status` **(free)** — `view=\"status\"` (NYSE open/close,\n  default) or `view=\"scan_dates\"` (which scan dates have data).\n- `get_playbook` **(free)** — methodology + reference: no arg lists the\n  catalog; `name=` fetches a playbook (`start-here`, `daily-workflow`,\n  `run-your-own-tournament`, `exit-lab`, `leakage-and-data-contract`,\n  `changelog`) or `name=\"schema\"` the machine-readable data contract (per-column\n  leakage classification); `field=` explains any signal field (deterministic,\n  no LLM). Playbooks are also MCP resources (`gammarips://playbooks/{name}`).\n- `get_daily_report` **(free)** — `view=\"report\"` (full daily report, default)\n  or `view=\"list\"` (recent reports).\n\n### Removed\n`web_search` (V4). The engine's own daily selection is not published same-day\n(`get_todays_pick` / `list_todays_picks` / `get_open_position` removed in V3);\nrealized receipts remain via `query_outcomes(view=\"positions\")`.\n\n## Prompts\n\n`morning_brief`, `analyze_candidate(ticker)`, `run_your_own_tournament` — thin orchestrations over the tools above. None returns a pick.\n\n## Quick connect\n\n### Claude Code\n\n```bash\n# Free tier (no key):\nclaude mcp add --transport http gammarips https://mcp.gammarips.com/mcp\n\n# Pro (with your key):\nclaude mcp add --transport http gammarips https://mcp.gammarips.com/mcp \\\n  --header \"Authorization: Bearer gr_live_your_key\"\n\n# Pro with OAuth instead of a key (sign in once in the browser, tokens refresh):\nclaude mcp add --transport http gammarips https://mcp.gammarips.com/pro\n# then run /mcp inside Claude Code and choose \"Authenticate\"\n```\n\n### ChatGPT, Claude (claude.ai / Desktop), and other OAuth chat clients\n\nAdd a custom connector / remote MCP server with the URL\n`https://mcp.gammarips.com/pro`. The client discovers the authorization server\n(gammarips.com), registers itself (Client ID Metadata Document or dynamic\nregistration), and opens the GammaRips sign-in + consent page. No key to paste.\nNot subscribed yet? The connection still works on the free tools and the pro\ntools answer with the subscribe steps; pro access applies on the next token\nrefresh (within an hour) after you subscribe, or when you reconnect.\n\n### Headless agents (a VM, a cron, a server): machine clients\n\nFor an agent with no browser and no human, create a **machine client** on\n[gammarips.com/account](https://gammarips.com/account) (Agent Access required).\nYou get a `client_id` + `client_secret` (shown once). Mint a one-hour access\ntoken with the `client_credentials` grant and send it as a bearer:\n\n```bash\nTOKEN=$(curl -s -u \"$GR_CLIENT_ID:$GR_CLIENT_SECRET\" \\\n  -d grant_type=client_credentials \\\n  -d resource=https://mcp.gammarips.com/pro \\\n  https://gammarips.com/oauth/token | jq -r .access_token)\n\n# Claude Code headless (claude -p), with the token in .mcp.json:\n#   { \"mcpServers\": { \"gammarips\": { \"type\": \"http\",\n#       \"url\": \"https://mcp.gammarips.com/pro\",\n#       \"headers\": { \"Authorization\": \"Bearer ${GAMMARIPS_MCP_TOKEN}\" } } } }\nGAMMARIPS_MCP_TOKEN=\"$TOKEN\" claude -p \"...\" \n```\n\nMint before each run: there is no refresh token for machine clients, and the\ntier is re-read from your subscription on every mint. An API key still works\nfor the same purpose; the machine client is the short-lived-credential option.\n\n### Cursor\n\n**Easiest — install the plugin.** This repo is an [Open Plugins](https://open-plugins.com)-standard plugin (`.cursor-plugin/plugin.json`): it bundles the hosted MCP server plus a `gammarips-options-flow` skill that teaches your agent the data-not-advice workflow. Install it from the plugin marketplace (search \"GammaRips\") or point Cursor at this repo. It connects on the free tier out of the box; add your `gr_live_...` key for pro tools.\n\nManual: Settings → MCP → Add new MCP server, or add to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"gammarips\": {\n      \"url\": \"https://mcp.gammarips.com/mcp\",\n      \"headers\": { \"Authorization\": \"Bearer gr_live_your_key\" }\n    }\n  }\n}\n```\n\nOmit `headers` for the free tier.\n\n### Cline\n\nMCP Servers → Remote Servers → Add, or add to `cline_mcp_settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"gammarips\": {\n      \"url\": \"https://mcp.gammarips.com/mcp\",\n      \"type\": \"streamableHttp\",\n      \"headers\": { \"Authorization\": \"Bearer gr_live_your_key\" }\n    }\n  }\n}\n```\n\nOmit `headers` for the free tier (5 anon tools).\n\n### Generic MCP config\n\n```json\n{\n  \"mcpServers\": {\n    \"gammarips\": {\n      \"url\": \"https://mcp.gammarips.com/mcp\"\n    }\n  }\n}\n```\n\nClients that only speak SSE can use the legacy `/sse` endpoint during the deprecation window.\n\nFree tier works with no account: `get_pool`, `get_regime_context`, `get_market_calendar_status`, `get_playbook`, `get_daily_report`. Pro tools (`get_signal`, `get_liquidity`, `query_outcomes`, `replay_contract`) require Agent Access ($29/mo, 30-day free trial) — generate a key at [gammarips.com](https://gammarips.com/pricing), or connect through `/pro` and sign in.\n\n## Local development\n\n### Prerequisites\n\n- Python 3.10+\n- Optional: Docker\n\n### Setup\n\n```bash\ngit clone https://github.com/DevDizzle/gammarips-mcp.git\ncd gammarips-mcp\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .\ncp .env.example .env\n```\n\n### Run locally\n\n```bash\nPYTHONPATH=src python src/server.py\n```\n\nThe server binds to `0.0.0.0:${PORT:-8080}`, Streamable HTTP at `/mcp` (SSE fallback).\n\n### Docker\n\n```bash\ndocker build -t gammarips-mcp .\ndocker run --rm -p 8080:8080 --env-file .env gammarips-mcp\n```\n\n## Environment\n\nSee `.env.example` for the current environment variables. Typical values include:\n\n- `GCP_PROJECT_ID`\n- `FIRESTORE_DATABASE`\n- `GCS_BUCKET_NAME`\n- `LOG_LEVEL`\n- `PORT`\n- `REQUIRE_API_KEY` / `AUTH_SHADOW` (API-key gate mode)\n- `OAUTH_ENABLED` / `OAUTH_ISSUER` / `OAUTH_JWKS_URL` / `OAUTH_MCP_RESOURCE_ORIGINS`\n  (OAuth 2.1 resource server; defaults are production, see `src/utils/oauth.py`)\n\n## Validation\n\n### Python compile check\n\n```bash\npython -m compileall src\n```\n\n### Docker build check\n\n```bash\ndocker build -t gammarips-mcp:test .\n```\n\n## Deployment\n\nDeployment is **manual** (the CD workflow was removed; `.github/workflows/ci.yml`\nonly runs `ruff format --check` + `ruff check` on pushes/PRs to `main`).\n\nShip a new revision with the deploy script, which uses a Cloud Run **source\ndeploy** and reproduces the live config exactly (secrets via Secret Manager,\n`REQUIRE_API_KEY=false`):\n\n```bash\nbash scripts/deploy.sh\n```\n\nEquivalent one-liner:\n\n```bash\ngcloud run deploy gammarips-mcp --source=. \\\n  --project=profitscout-fida8 --region=us-central1 \\\n  --set-env-vars=\"REQUIRE_API_KEY=false\" \\\n  --set-secrets=\"POLYGON_API_KEY=POLYGON_API_KEY:latest,GOOGLE_API_KEY=GOOGLE_API_KEY:latest,GOOGLE_CSE_ID=GOOGLE_CSE_ID:latest\"\n```\n\n> The API keys are mounted from Secret Manager — never pass them as plain env\n> vars (that clobbers the secret mounts).\n\n**Before any deploy that changes data exposure: run the `gammarips-review` leakage audit** (see `docs/MCP-V3-SPEC.md` §2.4).\n\n## Security\n\nSee [`SECURITY.md`](./SECURITY.md) for the trust model — read-only guarantee,\nparameterized-query SQL-injection defense, response-size bounds, per-IP rate\nlimits, sanitized errors, leakage-safe views, the column-classification\ndata contract, and the OAuth 2.1 resource-server model (this service only\nverifies tokens; gammarips.com is the authorization server).\n\n## License\n\nMIT\n",
  "bytes": 12620,
  "sha": "a22497250c96e1965e6549356e4824c82503c481024345cf732a305b840a146b",
  "repo_slug": "devdizzle/gammarips-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_devdizzle_gammarips_74d91d7f/readme"
}