# ELDRICK API > ELDRICK is the golf club fitting MCP server for AI agents and developers: fittings for drivers, fairway woods, hybrids, irons and wedges, plus a catalog of real heads, shafts and grips. It works inside ChatGPT, Claude, Gemini, Microsoft Copilot, Perplexity, Le Chat, Meta Muse, Grok and Cursor from one URL: https://api.eldrick.com/mcp Built on 100,000+ fittings, including 25,000+ ELDRICK has run. Public API v1 fits drivers, fairway woods, hybrids, irons and wedges (not putters). - Methodology: https://eldrick.com/methodology - AI golf club fitting: https://eldrick.com/ai-golf-club-fitting - Store: https://store.eldrick.com - Use ELDRICK in an AI assistant (for golfers): https://eldrick.com/ai-assistants - Full reference, generated from the live MCP server: https://api.eldrick.com/llms-full.txt ## What This API Does ELDRICK analyzes golfer measurements and swing data and returns equipment specs: loft, shaft flex, shaft weight, length, lie angle, head profile and swing weight, plus wedge bounce and set gapping and fairway/hybrid gapping. Each fitting is matched to real heads, stock and aftermarket shafts and grips. Free read-only tools search the catalog, compare clubs, score clubs for a golfer and build store.eldrick.com links. ## MCP (recommended for agents) One remote MCP server works with ChatGPT, Claude, Gemini, Microsoft Copilot, Perplexity, Le Chat, Meta Muse, Grok, Cursor, VS Code and any MCP client. Directory listings are still in review on some platforms; everywhere, you can add ELDRICK by URL today as a custom connector. - Endpoint: https://api.eldrick.com/mcp (Streamable HTTP, stateless; POST) - Auth: OAuth 2.1 (sign in with an ELDRICK account) or `Authorization: Bearer ` header. Never put credentials in tool arguments. - Without an account: https://api.eldrick.com/mcp/free (no credential). The club tools work there: search_clubs, get_club, compare_clubs, score_clubs, build_store_link, build_checkout_link, get_grip_size, analyze_bag_gapping and find_fitter, with short result pages (up to 10 clubs) and rate limits. Fittings (analyze_fitting, get_fitting) need a free ELDRICK account: there they return SIGN_IN_REQUIRED with a sign-in link and an OAuth challenge in `_meta["mcp/www_authenticate"]`. Relay the sign-in link to the golfer. Free tool results end with a one-line `nudge` toward a fitting; pass it on once, briefly. - OAuth discovery: https://api.eldrick.com/.well-known/oauth-protected-resource/mcp and https://api.eldrick.com/.well-known/oauth-authorization-server (PKCE S256; Client ID Metadata Documents; dynamic client registration at /oauth/register; public clients use token auth "none", pre-registered confidential clients use client_secret_basic or client_secret_post) - Health (no auth): https://api.eldrick.com/mcp/health - MCP Server Card (SEP-2127): https://api.eldrick.com/mcp/server-card (also /.well-known/mcp.json and /.well-known/mcp/server.json) - AI Catalog: https://api.eldrick.com/.well-known/ai-catalog.json - Official MCP Registry entry: https://api.eldrick.com/server.json (com.eldrick.api/fitting) Step-by-step setup for ChatGPT, Claude, Claude Code, Microsoft Copilot, Gemini, Perplexity, Le Chat, Meta Muse, Grok, Grok developers (xAI API), Cursor, VS Code and Windsurf: https://api.eldrick.com/connect To connect any MCP client: add a remote (HTTP) MCP server with URL `https://api.eldrick.com/mcp`. If the client supports OAuth, sign in with your ELDRICK account when prompted. Otherwise set the header `Authorization: Bearer eld_...` (or a short-lived `eat_` Agent Connection token). Tools (14; 12 for AI-assistant users, see below; every argument and output field: https://api.eldrick.com/llms-full.txt): - analyze_fitting: run a new fitting (driver, fairway, hybrid, iron or wedge). Uses one included fitting or credit. Returns specs, matched products, topPicks with store links, a fittingId, and woodFit/wedgeFit for those clubs. Driver fittings accept totalDistance (150-500 yards, carry plus roll). - get_fitting: a fitting from this account: the result, or the status of one still running (it waits up to waitSeconds, default 20; "specs_ready" carries the final specs and matched clubs while the written analysis is being written). - show_fitting: shows a saved fitting from this account as the fitting card again, when the golfer asks to see a past fitting (never right after analyze_fitting, which already shows the card). - search_clubs: search/filter heads by club type, brand, category, price, hand, keywords. Free. - get_club: one head with lofts, stock shafts, upgrade shafts, grips, lengths, lies, sets. Free. - compare_clubs: 2-4 heads side by side. Free. - score_clubs: rank clubs for a completed fitting (any club type; wedge fittings return their matched wedges), a golfer such as {"speed": 95, "miss": "slice"} (swingSpeed, missPattern and handedness also accepted) or a preset (0-100 fit score, verdict, reasons, evidence, suggested shaft). Free. - build_store_link: a store.eldrick.com link to a club's page with every fitted spec in the URL (see https://api.eldrick.com/llms.txt#store-link-parameters). Opens the product page, never checkout. Free. - build_checkout_link: the same build as a one-tap checkout link (https://store.eldrick.com/checkout?build=, valid 72 hours). It opens ELDRICK's checkout with the build in the bag; nothing is charged until the golfer pays on that page. Use it when the golfer wants to buy. Free. - get_grip_size: grip size (junior, undersize, standard, midsize, jumbo) and extra wraps (none, +1, +2) from hand length and longest-finger length in inches, with the reasoning from the master fitter hand chart and catalog grips in that size. Free, deterministic. - analyze_bag_gapping: carry and loft gaps between consecutive clubs in a golfer's set, flags (gap too big or too small, overlap, duplicate loft, wedge gap too wide), the recommended wedge set from the PW loft, and suggested changes (add, drop, replace, change loft), each with the analyze_fitting club type to fit (fitWith). Missing carries are estimated from loft and driver or 7-iron speed and marked. Free, deterministic. - find_fitter: club fitters near a US ZIP, a city and state, or lat/lng (radius default 50 miles; filter by services driver, fairway_hybrid, irons, wedges, putter, full_bag and by brand): name, address, phone, website, booking link, distance, recognition, rating with its source, services, brands. ELDRICK partners within the radius come first, labelled "ELDRICK partner". Free. - check_key_status: included fittings, credits, reset date. - get_api_status: API, fitting and ruleset versions, and supported club types. Every tool returns structuredContent (with an outputSchema) and the same JSON as text. Read-only tools are annotated readOnlyHint=true; analyze_fitting is readOnlyHint=false, destructiveHint=false. check_key_status and get_api_status are developer tools: an `eld_` API key or `eat_` Agent Connection token lists and calls them; an end user's OAuth connection from an AI assistant (ChatGPT, Claude, Gemini, Copilot, Muse and others) does not see them. Their REST twins, GET /v1/key/status and GET /v1/status, work for every credential. Fitting flow for agents: 1. Ask, in order: which club; right- or left-handed; swing speed (or ball speed) in mph with that club; usual miss. Then offer optional extras (handicap, carry/total distance, height and wrist-to-floor, launch-monitor numbers). Never invent a number. 2. Call analyze_fitting once, with an idempotencyKey. A fitting takes about 20-50 seconds; the server sends MCP progress notifications (notifications/progress) when the request has a progressToken. 3. analyze_fitting returns as soon as the specs and matched clubs are final, with status "completed": show them now. With detail=true it also waits for the written analysis; if that is not ready within waitSeconds the status is "specs_ready" and get_fitting with the fittingId returns the full result. If the result has status "running" (it waited waitSeconds, default 25, or you sent async=true), call get_fitting with its fittingId until status is "completed". Do not call analyze_fitting again: on an end user's platform connection, or without an idempotencyKey, the same details within 10 minutes return the same fitting (not charged); a developer key that sends a new key starts and uses another fitting. 4. If status is "failed", call analyze_fitting again with the same input and the returned retry.idempotencyKey. The retry does not use another fitting. 5. Show specs and topPicks with "Fit by ELDRICK". Prompts: fit_club, fit_driver, compare_clubs, clubs_for_my_swing, check_my_bag (bag gapping). Resources: eldrick://guide/fitting-interview (questions by club), eldrick://docs/store-link-params, eldrick://guide/bag-gapping (gapping rules and thresholds), eldrick://guide/grip-size (hand chart). Hosts that support MCP Apps (io.modelcontextprotocol/ui) render a fitting card (ui://eldrick/fitting-card-v3.html) once per fitting: on analyze_fitting, and on show_fitting when a saved fitting is asked for again. get_fitting has no card. A running card checks get_fitting through the host until the fitting finishes; other clients read the same structuredContent. ## Grok (developers) The xAI API attaches remote MCP servers as a server-side tool: put ELDRICK in the request's tools and xAI connects to https://api.eldrick.com/mcp and calls its tools itself. Supported in the Responses API (OpenAI-compatible, POST https://api.x.ai/v1/responses) and the xai-sdk for Python; xAI does not document it for the legacy Chat Completions endpoint. Source: https://docs.x.ai/developers/tools/remote-mcp Tool fields (Responses API): type "mcp", server_url (required), server_label (required), server_description, allowed_tools (a list of ELDRICK tool names; omit for all), authorization (your ELDRICK `eld_` key; xAI sends it in the Authorization header, and ELDRICK accepts it with or without "Bearer "), headers. The xai-sdk spells two of them allowed_tool_names and extra_headers. Read both keys from the environment; never hard-code them or put them in a prompt. Python (pip install xai-sdk): ```python import os from xai_sdk import Client from xai_sdk.chat import user from xai_sdk.tools import mcp client = Client(api_key=os.environ["XAI_API_KEY"]) chat = client.chat.create( model="grok-4.7", tools=[mcp( server_url="https://api.eldrick.com/mcp", server_label="eldrick", authorization=os.environ["ELDRICK_API_KEY"], extra_headers={"X-ELDRICK-Platform": "grok"}, )], ) chat.append(user("Fit me for a driver. Right-handed, 98 mph, I slice it.")) print(chat.sample().content) ``` Responses API: ```bash curl https://api.x.ai/v1/responses \ -H "Authorization: Bearer $XAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-4.7", "input": [{"role": "user", "content": "Fit me for a driver. Right-handed, 98 mph, I slice it."}], "tools": [{ "type": "mcp", "server_url": "https://api.eldrick.com/mcp", "server_label": "eldrick", "authorization": "'"$ELDRICK_API_KEY"'", "headers": {"X-ELDRICK-Platform": "grok"} }] }' ``` - Optional header X-ELDRICK-Platform: grok reports the traffic under Grok; X-ELDRICK-Traffic: test keeps test runs out of usage reports. Neither changes billing. - Each analyze_fitting uses one fitting; every other tool is free. Follow the fitting flow above: interview in order, one analyze_fitting with an idempotencyKey, get_fitting while it runs, show "Fit by ELDRICK". - Starter: a ready Grok club fitter (Python and TypeScript, system prompt included) at https://github.com/chadwittman/eldrick-grok-bot - Grok users without code: grok.com/connectors, New Connector, Custom, paste https://api.eldrick.com/mcp, sign in. ELDRICK is not in Grok's connector catalog. On Grok Business and Enterprise an admin adds it first at console.x.ai (Grok Business, Connectors, Add Connector, Other). ## REST: How To Use 1. Get an API key at https://api.eldrick.com 2. Submit golfer data and swing metrics (POST /v1/fitting/analyze) 3. Receive structured equipment specs, plus (driver and iron) a short-lived `labUrl` for the visual Lab experience, and optional detailed analysis with ?detail=full 4. Save the fittingId; retrieve its durable evidence later with GET /v1/fittings/{fittingId} Optional specs first: add ?specsFirst=1 (or the header "Prefer: specs-first") and the response comes as soon as the specs and matched clubs are final (in a 20-fitting replay, a median 10 seconds sooner), with "status": "specs_ready" and "writeUp": { "status": "pending" }. The written analysis is saved to the fitting when done (GET /v1/fittings/{fittingId}). Without the opt-in the response is unchanged. 5. Driver and iron: open the returned `labUrl` to let the user explore that fitting visually. For older clients, POST /v1/fittings/{fittingId}/lab-handoff creates the same 15-minute signed URL. The URL contains no API key or account identity. Free catalog endpoints (fittings:read scope, no fitting quota): - GET /v1/catalog/clubs?clubType=&brand=&category=&minPrice=&maxPrice=&q=&hand=&sort=&limit=&offset= - GET /v1/catalog/clubs/{headId} - POST /v1/catalog/compare { "headIds": ["...", "..."] } - POST /v1/catalog/scores (fit scores; see OpenAPI) - GET /v1/catalog/evidence - GET /v1/catalog (the full catalog) - POST /v1/store/link { "headId", "fittingId?", "hand?", "loft?", "shaftId?", "flex?", "length?", "lie?", "gripId?", "gripSize?", "set?" } Free fitting tools (fittings:read scope, no fitting quota; the same inputs and outputs as the MCP tools): - POST /v1/grip-size { "handLengthIn", "fingerLengthIn?", "gloveSize?", "handedness?", "includeGrips?" } (get_grip_size) - POST /v1/bag/gapping { "clubs": [{ "club", "type?", "loft?", "carry?", "total?" }], "driverSpeed?", "sevenIronSpeed?", "attackAngle?", "lobWedgeFullSwing?" } (analyze_bag_gapping) - GET /v1/fitters?zip= (or city=&state=, or lat=&lng=) &radiusMiles=&services=driver,irons&brand=&limit= (find_fitter) ## Required Data - clubType: "driver", "fairway", "hybrid", "iron" or "wedge" - golfer.handedness: "left" or "right" - swingMetrics.swingSpeed: float mph (or provide ballSpeed instead), measured with the club being fitted What swingSpeed means per club: - driver: driver speed - fairway: driver speed by default; set clubDetails.fairwaySpeedSource = "three_wood" when it is 3-wood speed (converted to driver-equivalent before fitting) - hybrid: the hybrid's own speed - iron: 7-iron speed - wedge: the wedge's own speed ## Recommended Data - golfer.wristToFloor: float inches (20-50); without it lengths stay standard - golfer.handicap: -5 to 25 (or "25+") - golfer.averageScore: average 18-hole score (60-150), only for a golfer with no handicap - swingMetrics.ballSpeed, swingMetrics.launchAngle, swingMetrics.spinRate, swingMetrics.attackAngle (wedge bounce reads attack angle) ## Club-Specific Data (fairway, hybrid, wedge) - currentEquipment.loft: the loft being fitted (fairway 12-23, hybrid 17-28, wedge 44-62; a wedge defaults to 52, or by clubDetails.wedgeHit) - clubDetails.fairwayDesignation: "3-wood" | "5-wood" | "7-wood" (fairway) - clubDetails.fairwaySpeedSource: "driver" | "three_wood" (fairway) - clubDetails.driverSpeed: measured driver mph (fairway, hybrid) - clubDetails.sevenIronSpeed: measured 7-iron mph (wedge) - clubDetails.pwLoft: pitching wedge loft 35-52 (wedge set gapping) - clubDetails.lobWedgeFullSwing: "yes" | "no" | "unsure" (wedge) - clubDetails.wedgeHit: "PW" | "GW" | "AW" | "UW" | "SW" | "LW" (wedge): which wedge the numbers were hit with; read against that club (GW/SW table, stock length GW 35.5" / SW 35.25" / LW 35" steel) and, without a loft, sets it (GW 50, SW 56, LW 60). Wedge spin is graded up to 11,000 rpm. Wedge results return wedgeFit.wedgeHit and matchingCriteria.headCategory "Blade" | "Cavity back". - clubDetails.ironFittingId: a completed iron fitting from this account (wedge; carries its shaft and 7-iron speed) - clubDetails.ironShaft: { flex, weightGrams, material, launchProfile } (wedge, without ironFittingId) ## Optional Data - golfer.heightFeet, golfer.heightInches, golfer.weight - swingMetrics.clubPath, swingMetrics.faceAngle, swingMetrics.carryDistance - swingMetrics.totalDistance: driver carry plus roll, 150-500 yards - swingMetrics.strikePattern: "heel" | "toe" | "center" | "mix" - swingMetrics.missPattern: "fade" | "hook" | "straight" | "both" - swingMetrics.missSize: "slight" | "moderate" | "large", how big the miss is; a driver miss moves the weight (or earns a Draw Bias head), and a fairway/hybrid slice earns the Draw head, only when moderate or large; slight or omitted keeps Standard; a "less-slices" / "less-hooks" fix counts as moderate - currentEquipment.brand, model, shaftModel, length, shaftWeight - currentEquipment.shaftLaunchProfile: "Low" | "Mid-Low" | "Mid" | "Mid-High" | "High", the launch of the shaft the golfer plays now (launch rules step from it; omitted = unknown, Mid) - preferences.tempo, preferences.transition, preferences.shaftType, preferences.goals ## Authentication Bearer token via Authorization header. Keys use the "eld_" prefix. OAuth access tokens use "eoa_"; Agent Connection tokens use "eat_". ## Agent Connections For agents, use OAuth or an ELDRICK Agent Connection instead of giving a model an `eld_` API key. 1. A human administrator creates a named Agent Connection in the developer dashboard API with allowed scopes. 2. The administrator stores the one-time `eac_` host credential in the agent host's secure vault, not in prompts, source code, or tool arguments. 3. The host exchanges it at `POST /v1/agent/token` for a short-lived `eat_` Bearer token. 4. The host supplies the `eat_` token to REST or MCP. It expires after 15 minutes by default and is immediately rejected when the connection is revoked. Scopes: `fittings:create`, `fittings:read`, `sessions:ingest`. Dashboard management endpoints (Dashboard Bearer session required): - `GET /api/developers/me/agent-connections` - `POST /api/developers/me/agent-connections` with `{ "name", "scopes", "expiresAt?" }` - `DELETE /api/developers/me/agent-connections/{connectionId}` ## Reliable Agent Use - Send a unique `Idempotency-Key` header (MCP: idempotencyKey argument) when creating a fitting. Retrying the same request returns the original fitting without consuming a second fitting request. Reusing that key with a different payload returns 409. While the first request is still running, a retry returns 409 with Retry-After (MCP: it waits for the result). If the first attempt failed or was interrupted, the retry runs the fitting again under the same fittingId and does not use another fitting. - `X-ELDRICK-Traffic: internal` (or `test`) marks your own test traffic so it is left out of per-platform usage reporting. It does not change billing or limits. - Each fitting response includes `X-Request-ID`; preserve it in agent traces and support requests. - Optional `X-ELDRICK-Platform` and `X-ELDRICK-Client` headers name your platform and client for usage reporting. OAuth connections are attributed automatically. - Accounts connected through an AI platform with OAuth have a daily fitting limit (default 50 per account per UTC day). Over it, analyze_fitting returns `DAILY_CAP_REACHED` with `resetsAt` and `retryAfter`; catalog tools keep working. API keys are not affected. - `GET /health` is public liveness. `GET /readyz` verifies application, database, and every configured AI provider. `GET /mcp/health` proves the MCP server lists its tools. - `GET /v1/status` (Bearer auth) returns the active API, fitting and ruleset versions. ## Base URL https://api.eldrick.com ## CLI Tool Install the ELDRICK CLI for terminal-based access: ``` npm install -g eldrick-cli ``` Requires Node.js 18+. Commands: - eldrick login: save your API key (validates via /v1/key/status) - eldrick fit: interactive club fitting analysis (or pass flags: --club-type driver --swing-speed 95); pass --idempotency-key when an agent may retry - eldrick fittings get : retrieve a durable fitting record; use --json for agent-safe output - eldrick usage: show monthly usage and quota - eldrick whoami, eldrick logout, eldrick config set-url , eldrick config show Package: https://www.npmjs.com/package/eldrick-cli ## Documentation Full API docs: https://api.eldrick.com/docs Full reference for agents (every MCP tool, argument, prompt and resource): https://api.eldrick.com/llms-full.txt MCP Server Card: https://api.eldrick.com/mcp/server-card Connect ELDRICK to an AI platform: https://api.eldrick.com/connect OpenAPI spec: https://api.eldrick.com/openapi.json (also /v1/openapi.json) Privacy: https://api.eldrick.com/privacy Terms: https://api.eldrick.com/terms Support: https://api.eldrick.com/support ## Agent Verification The API repository includes `npm run verify:agent`. It checks health, database readiness, authenticated contract status, a fixture fitting, idempotent replay, and durable retrieval. Set `ELDRICK_API_BASE_URL` and `ELDRICK_API_KEY` in the agent environment; never put credentials in source, prompts, or MCP tool arguments. ## Attribution Display "Fit by ELDRICK" when showing fitting recommendations to users. ## Store link parameters build_store_link (and analyze_fitting topPicks[].storeUrl) open https://store.eldrick.com/club/?. Parameters: hand, loft (degrees, no ° sign), shaft (shaftId), flex, shaftWeight (band, e.g. 60-69g), length, lie (not drivers), grip, gripSize, set (irons: 4-PW, 5-PW, 6-PW), swingWeight, wood (fairway: 3-wood, 5-wood, 7-wood), bounce (wedge, degrees), wedges (wedge set as loft:bounce pairs, e.g. 50:8,54:10,58:6), fit (fittingId), utm_source, utm_medium, utm_campaign, utm_content, eld_ref. Full table: eldrick://docs/store-link-params.