Connect an agent

Any MCP (Model Context Protocol) agent can ask the Desk free questions, such as a team's record, with the Desk's MCP server address alone. For forecasts and your own teams, sign in from your app with your email, or send a free key.

ChatGPT and the Claude app connect with the address alone and sign you in when a question needs you. Use the Desk in ChatGPT has their steps.

Get a key

Make your key on the agent page:

1. Choose Sign in to get a key and sign in.
2. Choose Get a key. The page shows your key once and the Desk keeps no copy, so save it like a password.
3. Choose Copy setup prompt with your key and paste the prompt into your agent.

You hold one key at a time, so choosing Make a new key turns off the old one. To turn your key off without replacing it, choose Revoke key.

Connect Claude Code

You can sign in with your email instead of a key, so no key sits in Claude Code's settings file. Run this command, then run /mcp in Claude Code, choose the Desk and sign in:

claude mcp add -s user --transport http tennisdesk \
  https://thetennisdesk.com/api/mcp

But to use a key, run this command. It adds the Desk to Claude Code in every folder, not only the one you run it in. Put your key in place of <key> on its last line:

claude mcp add -s user --transport http tennisdesk \
  https://thetennisdesk.com/api/mcp \
  --header "Authorization: Bearer <key>"

But that command saves your key as plain text in Claude Code's settings file. To keep it out, put your key in an environment variable named TENNISDESK_KEY and run this command instead:

claude mcp add -s user --transport http tennisdesk \
  https://thetennisdesk.com/api/mcp \
  --header 'Authorization: Bearer ${TENNISDESK_KEY}'

Connect Cursor

Add this to .cursor/mcp.json, with your key in place of <key>:

{
  "mcpServers": {
    "tennisdesk": {
      "url": "https://thetennisdesk.com/api/mcp",
      "headers": { "Authorization": "Bearer <key>" }
    }
  }
}

Connect another MCP client

Point your client at https://thetennisdesk.com/api/mcp for free questions with no key, but for your teams or forecasts, sign in or send the header Authorization: Bearer <key> with each request.

Can ChatGPT or the Claude app connect?

Yes, on the web, on a computer or on a phone. Add the Desk by its address, as Use the Desk in ChatGPT shows. Free questions need no sign-in. For a forecast or your own teams, the app asks you to sign in to the Desk with your email, and then asks as you.

Check that it worked

Ask your agent to list the Desk's tools, which costs none of your calls, and if plan_lineup is on the list, your agent can reach the Desk.

What your agent can ask

Your agent can look up records, rosters, Desk levels and standings for covered players, teams, clubs and leagues, with or without a key. Agent tools lists each tool with a question to ask it.

You can name a team, a player or a club by pasting the link to its Desk page. A link also settles which player you mean when two share a name.

One query_club call returns what a club page shows, including, for each team with a team match left, whether it can still finish first.

Call query_club with briefing set to true for the club's week instead: its team matches in the 7 days from the call, and the club page's checks.

Your agent can also read these docs with read_docs.

Your agent can also fill in USTA NorCal's forms, step by step.

The Desk keeps what your agent asks, and also sends it to PostHog, one of the services that help run the site.

How many calls your agent gets

Your account gets 40 tool calls a day and 150 a month, free, with or without a Desk Pass. The count follows your account, not the key, so a new key keeps the count the old one had. A read_docs call doesn't count toward the day's or month's calls, so your agent can still read the docs after it reaches either limit. Your agent's calls are counted apart from your questions in the chat.

Get forecasts in your agent

Your agent asks for a forecast with these tools:

• plan_lineup
• predict_matchup
• project_standings
• scout_team

With a Desk Pass, your agent gets the whole forecast. Your key shares your free weekly forecast with the chat if your account has an email address. After that, a forecast tool returns free_forecast_used, which comes with a link to the pricing page. Your agent's forecasts share the chat's weekly limit, and How the forecast works says what each one shows.

When your agent hits a limit

When your agent reaches a limit, the Desk tells it why, so it can tell you. A refused call still counts toward the day's calls, so a forecast your agent asks for after the week's run out uses one too.

For developers: errors and status codes

• With a key the Desk doesn't recognize, before any call runs: HTTP 401, with the error mcp_key_not_recognized, which says what to do next.
• With an OAuth sign-in that expired or was revoked: HTTP 401, with the error invalid_token. Your app refreshes it or signs you in again.
• At the daily or monthly call limit: quota_exceeded, and the result names the limit it reached.
• When your free forecast this week is used: free_forecast_used. The result says when the next one comes.
• On a key with no account behind it: desk_pass_required.
• At the weekly forecast limit: forecast_limit_reached. The result carries the chat's message and one more line, which says each call until your forecasts come back still counts against the day's calls.
• When the Desk can't check your week's forecasts: forecast_check_failed.

With no key and no sign-in, a tool that answers about you or runs a forecast doesn't run. It returns sign_in_required, and every other tool still answers. What comes back, and what to do, depends on the client.

Client	What it gets	What to do
ChatGPT	HTTP 200, a tool result with isError set and a sign-in challenge in its _meta	Nothing: ChatGPT asks the person to sign in
The Claude app	HTTP 401, with a WWW-Authenticate header that names the OAuth metadata	Nothing: the app asks the person to sign in
Claude Code	The same HTTP 401	Run /mcp, choose the Desk and sign in, or connect with a key
Cursor	The same HTTP 401	Add your key, as in Connect Cursor
Another MCP client	The same HTTP 401	Sign in with OAuth from that header, or send your key

A counted forecast says how many are left this week in forecastsLeftThisWeek.

A call refused at a limit comes back as a tool result, with HTTP 200 and isError set, not as a 401, 403 or 429. A key that sends too many requests in a day is the one exception: it gets HTTP 429, with the error too_many_requests. Pings, tool lists and docs reads all count toward that limit, though they don't count as calls.