Optionsahoy MCP Server

OptionsAhoy MCP Server

Multi-year equity-compensation optimizer. Six tools that return the globally-optimal schedule across the candidate space. Full federal + 50-state + DC tax code.

Live MCP endpoint: https://optionsahoy.com/mcp (no auth, no install) Live REST API: https://optionsahoy.com/api/v1 OpenAPI 3.1 spec: /openapi.json Discovery manifests: /.well-known/mcp.json · /.well-known/openapi.json Agent integration docs: optionsahoy.com/for-agents

Built by AlphaLatitude Inc. — a pre-revenue beta-stage equity-compensation optimization product.

---

What this is

An optimization engine for equity-compensation tax planning, exposed as both a Model Context Protocol (MCP) server and a plain REST API. Six tools:

Each tool returns the globally-optimal schedule across the candidate space — not heuristics, not samples. Coverage spans the full federal tax code (ordinary brackets, long-term capital gains, AMT with credit recovery, FICA, NIIT) plus all 50 states and DC (state ordinary brackets, LTCG treatment, state AMT for CA, NY, MN). Same engine as the in-browser calculators at optionsahoy.com/tools; the API response is byte-identical to clicking through the tool.

Why use an optimizer

A benchmark of five frontier large language models on the same multi-year ISO exercise problem found that every one of 15 trials overshot the achievable after-tax outcome by 2x to 20x. Multi-year scheduling has a search space larger than an LLM can reason through in-context. Full write-up: HackerNoon — But can it do taxes though?

Use from Claude / ChatGPT / Perplexity / any MCP client

Add the server as a remote HTTP MCP connection:

https://optionsahoy.com/mcp

Or via the add-mcp CLI:

npx add-mcp https://optionsahoy.com/mcp

Use the REST API directly

# List endpoints
curl https://optionsahoy.com/api/v1

# Run an optimization
curl -X POST https://optionsahoy.com/api/v1/amt-iso \
  -H "content-type: application/json" \
  -d @input.json

Request body shapes are documented in public/openapi.json.

Repository layout

functions/         Cloudflare Pages Functions (MCP server + REST API endpoints)
  mcp.ts           HTTP MCP server
  api/v1/*.ts      Six REST endpoints + GET /api/v1 discovery
  _lib/*.ts        Shared helpers, calc-input parsers, MCP tool descriptors
lib/               Optimizer + tax-code logic
  calc/            Per-tool optimizer functions (computeAmtIso, etc.)
  tax/             Federal + 50-state + DC bracket data, AMT, FICA, NIIT
  markets/         Sector statistics
  options/         Black-Scholes, risk-free rates
  data/            Type definitions for option-chain data
public/            Static assets: OpenAPI spec, llms.txt, discovery manifests
tests/             Vitest suites (873+ tests including byte-identity assertions)

Run tests

npm install
npm test         # 870+ tests, ~3s on a laptop
npm run typecheck

Registry listings

• Official MCP Registry — io.github.AlvisoOculus/optionsahoy-mcp v1.0.0, status active
• Smithery
• add-mcp curated registry
• PulseMCP (cascades from Official Registry)

Use from Google Cloud (Gemini agents)

Google Cloud Agent Registry lets each GCP project register external MCP servers for use by Gemini agents. Registration is per-project (no central submission). Two paths:

# Path A: let the Agent Registry introspect our MCP endpoint
gcloud alpha agent-registry mcp-servers register \
  --uri=https://optionsahoy.com/mcp \
  --display-name="OptionsAhoy" \
  --location=us-central1 \
  --import-tools

# Path B: pass our published toolspec.json directly (faster, no introspection)
gcloud alpha agent-registry mcp-servers register \
  --uri=https://optionsahoy.com/mcp \
  --display-name="OptionsAhoy" \
  --location=us-central1 \
  --tool-spec=<(curl -sSL https://optionsahoy.com/toolspec.json)

The toolspec.json mirrors the MCP tools/list response with readOnlyHint and idempotentHint annotations on all six tools (all are pure deterministic calculators with no side effects). To regenerate after a tool-shape change:

curl -sS -X POST https://optionsahoy.com/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
  | jq -c '{tools: [.result.tools[] | . + {annotations: {readOnlyHint:true, idempotentHint:true, destructiveHint:false, openWorldHint:false}}]}' \
  > public/toolspec.json

License

See LICENSE. All rights reserved during beta; the deployed service at optionsahoy.com is free under terms.

Contact

For partnerships, early API access, MCP integration support: andrew@alphalatitude.com

Deployment topology

Two pieces serve the live endpoint:

1. Cloudflare Pages project (GitHub-connected to this repo) auto-deploys functions/ + public/ on every push to main → optionsahoy-mcp.pages.dev.
2. Cloudflare Worker in worker-proxy/ forwards optionsahoy.com/mcp* + /api/v1/* to that Pages deployment, so the public URL stays stable. One-time wrangler deploy — see worker-proxy/README.md.