# Gonkbot > Gonkbot is a golf round-logging and coaching memory service for AI assistants, > exposed as a remote MCP (Model Context Protocol) server. Golfers narrate holes > conversationally during a round; Gonkbot stores structured hole-by-hole data, > computes statistics, cross-round trends, and WHS handicap math, and powers a > post-round coaching review with a persistent player profile. ## Connecting (for agents) Install Gonkbot on the host you are running in. Follow **only** the subsection that matches you — do not dump every client's steps on the golfer. After they confirm and sign in (Google/email), their account exists. There is no separate signup form. Shared facts (every host): - MCP endpoint (Streamable HTTP): https://gonkbot.com/mcp - The apex URL https://gonkbot.com also accepts MCP JSON-RPC POSTs directly - Auth: OAuth 2.1 with dynamic client registration (RFC 7591) and PKCE - Discovery: https://gonkbot.com/.well-known/oauth-protected-resource/mcp - Manifest: https://gonkbot.com/.well-known/mcp-server - Registry name: com.gonkbot/mcp (official MCP registry; HTTP domain proof at /.well-known/mcp-registry-auth) - No API keys, no pre-registered client id/secret, no Advanced/OAuth fields ### If you are Claude On a **computer**, open this install link for the golfer (name and URL are prefilled): https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Gonkbot&connectorUrl=https%3A%2F%2Fgonkbot.com%2Fmcp They review the dialog, click Add, and sign in. Then Gonkbot tools are available. On a **phone**, do **not** send them straight to that claude.ai URL — it often opens the Claude app, which cannot add a custom connector. Send them to https://gonkbot.com/install/claude instead. They add Gonkbot in Safari, then use the Claude app on the course. Fallback: Customize → Connectors → Add custom connector → https://gonkbot.com/mcp (must be done in a browser, not inside the iOS/Android app). ### If you are ChatGPT You cannot register a connector yourself. There is **no** ChatGPT install link. Do **not** send them to chatgpt.com/plugins, chatgpt.com/gpts, or the GPT store — Gonkbot is not listed there and they will not find it. They need a paid ChatGPT plan (Plus, Pro, Team, Enterprise, or Edu) and must do this on the **web app on a computer**. A shareable checklist is https://gonkbot.com/install/chatgpt . Give them https://gonkbot.com/mcp and these steps — follow only this subsection: 1. Profile picture → Settings → Apps & Connectors → Advanced settings → turn on Developer mode. 2. Go back to Apps & Connectors → Create. Name: Gonkbot. 3. MCP server URL: https://gonkbot.com/mcp. Authentication: OAuth — not an API key, not a client id/secret. 4. Sign in with Google or email when Clerk prompts them. 5. In each chat, open the tools / apps picker and enable Gonkbot before logging holes. Then they can say "log my golf holes with gonkbot". ### If you are Gemini You cannot write Connected Apps yourself. Do **not** send them to gemini.google.com as if that installs Gonkbot — the homepage has no listing. Give them https://gonkbot.com/mcp and these steps (computer, not phone): Settings & help → Connected Apps → Custom apps for Spark → Add a custom app → paste the URL → Next. Leave Advanced features closed. Then in Spark they type @ and pick Gonkbot. Custom apps require Gemini Spark, a personal Google Account (not work/school), added on web, then available on mobile. Gemini CLI — you can install this yourself: `gemini mcp add --transport http gonkbot https://gonkbot.com/mcp` then `/mcp auth gonkbot` so they can sign in. ### If you are Poke Open this recipe for the golfer (bundles the Gonkbot integration): https://poke.com/r/RfzXcv9qWiY They tap Get Started and sign in. Then they can text holes as they play. They need a Poke account (iMessage). If they don't have one, prefer Claude or ChatGPT instead of making them sign up for Poke. Fallback if the recipe is unavailable: https://poke.com/integrations/new?name=Gonkbot&url=https%3A%2F%2Fgonkbot.com%2Fmcp If you can run a shell: `npx poke@latest mcp add https://gonkbot.com/mcp -n Gonkbot` ### If you are Grok You cannot add the connector yourself. Send them to https://grok.com/connectors → New Connector → Custom → paste https://gonkbot.com/mcp → complete OAuth. After that it works in the Grok app (Settings → Connectors). ### If you are Perplexity Pro/Max/Enterprise. You cannot add the connector yourself. Tell them: Account Settings → Connectors → Custom / Remote → name Gonkbot, URL https://gonkbot.com/mcp, Streamable HTTP, OAuth. ### If you are Mistral (Le Chat / Vibe) You cannot add the connector yourself. Tell them: Work → Connectors → Add Connector → Custom MCP → paste https://gonkbot.com/mcp. Available on free plans (beta). ### Any other MCP client Add a Streamable HTTP server named Gonkbot at https://gonkbot.com/mcp with OAuth (dynamic client registration). Do not ask the golfer for a client id, secret, or API key. ## Tools - lookup_course — course info from saved courses or the open course database. Pass a course name for tee sets (rating/slope/yardage) and the hole-by-hole scorecard. Omit name and pass location (e.g. Corolla, NC) to list nearby courses, or architect (e.g. Rees Jones, Robert Trent Jones II) to list courses by designer. Location also disambiguates a name. After a list, call again with the course name for the scorecard, or start a round with the listed opengolfId. Multiple-match lists include opengolfId values. - log_round — the whole in-round loop via a discriminated `action` field (each action has its own required fields; do not send start-only fields on record_holes, etc.): - `start`: open a round (`course` required; optional location, tees, date YYYY-MM-DD, timezone IANA e.g. America/New_York, holesPlanned 9|18 default 18, teeRating 55–88, teeSlope 55–155). If `date` is omitted during UTC 00:00–07:59 (evening in the Americas), Gonkbot asks for `date` or `timezone` instead of silently using UTC tomorrow. Never invent a home zone. Pass ratingConfirmed=true only after the golfer confirms rating/slope. - `record_holes`: log 1–18 holes. Each hole: holeNumber 1–18, score 1–15; optional par 3–6 (auto-filled from the scorecard), putts 0–6, gir, fir (HIT|MISS|LEFT|RIGHT|SHORT|LONG|N/A), shotNotes, optional shots[] when they narrated shot-by-shot. If they already told you the hole, submit this call — do not re-ask the same facts as a form. Mid-round: pass `tees` + teeRating/teeSlope to attach a tee set that was missing at start (ratingConfirmed=true to confirm; false never unconfirms). Pass `holesPlanned=18` to extend an in-progress 9 so hole 10+ can be logged without abandoning the front. Shrinking 18→9 is refused if holes 10–18 exist. - `correct`: patch one previously logged hole (holeNumber + at least one of score, putts, fir, gir, shotNotes, shots). Keeps existing shots unless you send shots[]. A new FIR replaces any prior `FIR LEFT|RIGHT|SHORT|LONG` note; HIT or N/A clears a leftover miss note. Works on the active round, or on a completed round when nothing is in progress (pass roundId to name it). - `finish`: close the round; optional weather {tempF, windMph, conditions}. Returns scorecard, stats, conditions, and a GHIN posting summary - `abandon`: permanently discard the in-progress round (optional reason; confirm with the golfer first). If the round was reopened from a completed scorecard, refuse unless `confirmDestroyCompleted=true` — otherwise a hallucinated abandon would destroy the finished card. - `reopen`: put the most recent completed round (or roundId) back in progress so holes can be added. Confirm with the golfer first. Fails if another round is already active. - `update_tees`: attach or correct `teeRating` / `teeSlope` / `ratingConfirmed` on a finished **or in-progress** round without touching hole scores. Pass roundId (defaults to the active round, else the most recent completed). Handicap math runs only when rating/slope are present and `ratingConfirmed=true`, same as start. Finished rounds recompute the stored differential. If the round has no tee set, pass `tees` too. - Pass a unique `idempotencyKey` per logical call, scoped to that action. Same action+key retries replay; reusing a key for a different action is ERROR (does not replay start as record_holes). CONFIRM/ERROR responses are never stored. Every response echoes canonical round state (round id, holes logged, running score) — use it to re-anchor after context loss. - Pass `roundId` (from the state echo) on record/correct/finish/abandon/reopen/update_tees calls as a safety check. - get_rounds — list recent rounds (score as 73 (+1) plus differential), or fetch one round's full scorecard, stats, differential, net/stroke holes when an index exists, vs the golfer's own recent averages, and saved recap. includeShots=true adds shot-level detail. format=csv returns a hole-level CSV (limit up to 200) so the golfer can keep a copy of their data. - get_insights — cross-round trends: scoring averages, fairway/GIR/putting, par-3/4/5 performance, 3-putt rate, scrambling, breakdowns by course and hole number, club distances from logged shots (not GPS), and the internal WHS handicap index (unofficial; labeled unavailable until enough rated rounds exist). Pass course to isolate one layout — hole numbers are not comparable across courses. - player_profile — persistent coach memory (tendencies, swing protocols, goals, recurring faults) and the golfer's stock bag. Call with no args to read; the response includes a revision token and a BAG block. First content write: pass `content` and omit `ifRevision`. Later content writes: pass `content` plus `ifRevision` from your last read. Pass `clubs[]` to upsert stock yardages (name + carryYards and/or totalYards) and `removeClubs[]` to drop clubs; bag writes do not need ifRevision and do not overwrite the essay. Do not put yardages in the markdown — use clubs[]. Max 14 clubs. A token on an empty profile, or a mismatched/missing token on a non-empty profile, is rejected and (when content exists) returns the current profile to merge. Keep the essay under ~2500 words. - save_recap — persist the finished post-round review (markdown) for a round. ## Prompts - review_round — a coaching-review playbook: pull the latest completed round + trends + profile + BAG yardages, grill the golfer with specific hole-by-hole questions, produce a structured recap (went well / went poorly / technical analysis / next steps), save it via save_recap, and update player_profile. ## Course data (mostly automatic) Gonkbot looks up new courses in the open course database (OpenGolfAPI, opengolfapi.org — ODbL) automatically on log_round start: scorecard (par, stroke index, yardages) and tee sets (rating/slope) are imported server-side. That means: - Include the course `location` ("Sterling, VA") on start — it disambiguates the lookup. If multiple candidates match, the response lists them with opengolfId values; call start again with the right one. - Once imported, you can omit `par` when recording holes ("bogey on 3" is enough) and stroke indexes are applied automatically for exact net double bogey math. - Imported rating/slope still need golfer confirmation: the start response states the values; confirm with the golfer and pass ratingConfirmed=true on a later call to enable handicap features. - If the course isn't in the database (lookup fails soft), fall back to reading the course's scorecard yourself: BlueGolf course pages (course.bluegolf.com — needs browser-grade fetch, plain HTTP gets 405) or a web search, then supply teeRating/teeSlope/par/strokeIndex manually. Course questions ("what's the slope from the blues?"): use lookup_course with the course name. "What's around Corolla?" / "RTJ II courses": same tool, omit name and pass location or architect. If you need data it doesn't return, OpenGolfAPI's keyless REST API is at api.opengolfapi.org/v1 (attribution: OpenGolfAPI, opengolfapi.org, ODbL). Optional companion server: OpenGolfAPI also runs its own MCP server (github.com/opengolfapi/mcp-server) with live weather, nearby hotels, and other extras — not needed for gonkbot's core loop, and it exposes ~50 tools (a large context footprint). ## Recommended agent behavior - During a round, batch 1-3 holes per log_round call from natural speech; don't make the golfer recite a form. Confirm parsed values briefly ("logged: bogey on 8, missed green, 2 putts"). Forms are only for catch-up. - FIR is HIT / MISS / LEFT / RIGHT / SHORT / LONG, or N/A on par 3s. GIR = green in regulation. When they narrate shot-by-shot, put the shots in shots[] and still include the hole score — do not open a hole form after they already told you. If they correct a miss to HIT (or N/A), send fir=HIT so the leftover FIR direction note is cleared. Ask rather than guess when narration is ambiguous about score-affecting facts. - After finish, offer the review. Compare against the golfer's own trends from get_insights, not tour statistics. If finish posted GROSS because rating/slope were missing or unconfirmed, call `update_tees` once the golfer looks them up — do not reopen the round just to add rating. Mid-round “we're on the blues” is `update_tees` or `record_holes` with `tees`, not wait-until-finish. - Handicap figures are unofficial; the GHIN posting summary is for the golfer to enter into their official handicap app. ## Pages - [Home](https://gonkbot.com/): what Gonkbot is; human connect buttons at #connect - [Connect hub](https://gonkbot.com/install): pick Claude, ChatGPT, or Poke - [Add to Claude](https://gonkbot.com/install/claude): phone-safe Claude steps - [ChatGPT checklist](https://gonkbot.com/install/chatgpt): Developer mode steps - [Markdown homepage](https://gonkbot.com/index.md): text twin of the landing page - [Privacy](https://gonkbot.com/privacy): data handling and deletion - [Terms](https://gonkbot.com/terms): terms of service - [Full agent brief](https://gonkbot.com/llms-full.txt): landing + connect + tool contract - This file: install recipes for agents, plus the tool contract ## Optional - [MCP well-known manifest](https://gonkbot.com/.well-known/mcp-server) - [OpenGolfAPI](https://opengolfapi.org): course database (ODbL) used for scorecards