WhenWiz MCP server

WhenWiz exposes a public MCP server so an assistant can list, create, update, and delete the countdowns on your account. The server speaks Streamable HTTP, protocol 2025-06-18 and 2025-03-26.

Server URL:

https://api.whenwiz.com/mcp

Grok Bot and grok.com open a browser window and sign in with OAuth. No client id or client secret is entered. Clients that cannot open that window send an API key as a bearer token.

Connect from Grok Bot

In a Bot chat, ask it to add a custom MCP server. Say “custom MCP server” so it does not install a catalog plugin:

Add a custom MCP server named WhenWiz at https://api.whenwiz.com/mcp

Approve the add. Click Authorize on the card. A browser window opens on whenwiz.com. Sign in if you are signed out, then choose Allow. Return to the Bot and type @ to attach WhenWiz.

Grok Bot runs in the cloud, so a laptop address will not work. If a key is offered, enter it in the Bot’s masked secret field, not in the chat.

Connect from grok.com

Go to grok.com/connectors, choose New Connector, then Custom, and paste https://api.whenwiz.com/mcp. Complete the sign-in window. Leave the client secret empty. Grok discovers the authorization and token URLs.

A connector on grok.com is separate from one added in Grok Bot. Add it in each place you use it.

On a Grok Business or Enterprise team, an admin adds the connector before members can connect their own accounts.

Connect with an API key

On Account, Connections, choose Create an API key. The key is shown once and starts with wwk_. Send it on every request:

Authorization: Bearer wwk_...

POST https://api.whenwiz.com/mcp

Revoke the key on the same screen. Signed-in assistants, such as Grok, are listed there too and can be revoked. Revoking clears that grant’s access and refresh tokens.

Use a key for Cursor, a script, or any client that cannot open the OAuth window.

What the assistant can do

Every tool runs as the signed-in account. Draft and private countdowns stay visible only to that account. A missing countdown and someone else’s countdown both come back as not found.

Results include id, label, kind, status, display, timezone, config, revision, target_at, deadline_at, phase, live_state, remaining_seconds, and page_url.

revision is required when you change or control a countdown. If it does not match, read the countdown again and retry.

A missing timezone uses the account timezone. Timezones are IANA names, such as Europe/London. Abbreviations and numeric offsets are not timezones. A civil time that falls in a spring-forward gap is rejected. A civil time that happens twice uses the earlier instant. status defaults to private.

list_countdowns

List countdowns in account order.

• limit, optional, 1 to 100, default 25
• cursor, optional, the next_cursor from the previous page

Returns countdowns, next_cursor, and has_more.

get_countdown

Read one countdown you own.

• id, required

create_countdown

Create a countdown.

• label, required, 1 to 200 characters
• kind, required: datetime, fixed, duration, recurring, personalized, or business
• status, optional: draft, private, or published. Default private
• display, optional: until, since, or both. Default until
• config, optional. When sent, it is the full configuration for that kind

datetime and fixed config is one of:

• timezone, local_date (YYYY-MM-DD), and local_time (HH:MM)
• deadline_at, an ISO 8601 instant ending in Z or a numeric offset, plus an optional timezone for display
• start_now: true and timezone, to count up from now

duration config is duration_seconds, from 1 to 31536000. The timer is created idle. Start it with control_countdown.

recurring config is frequency (daily, weekly, monthly, or yearly), local_time, an optional timezone, and the fields that frequency needs: days_of_week (1 is Monday, 7 is Sunday) for weekly, day_of_month for monthly and yearly, and month (1 is January) or annual_date (YYYY-MM-DD) for yearly.

personalized and business use the same config the WhenWiz API accepts for those kinds.

update_countdown

Change a countdown you own. Send only the fields that change. config, when sent, replaces the kind configuration.

• id, required
• revision, required
• label, status, display, kind, and config, optional

Only datetime, fixed, and recurring can switch among those kinds. Other kinds stay fixed for the life of the countdown.

delete_countdown

Delete a countdown you own. This removes it.

• id, required

Returns deleted, id, and label.

control_countdown

Start, pause, resume, or reset a duration timer. Other kinds cannot be controlled.

• id, required
• revision, required
• action, required: start, pause, resume, or reset

Sign-in details

An unauthenticated POST /mcp returns 401 with:

WWW-Authenticate: Bearer resource_metadata="https://api.whenwiz.com/.well-known/oauth-protected-resource/mcp"

That document names the authorization server https://api.whenwiz.com. Its metadata is https://api.whenwiz.com/.well-known/oauth-authorization-server.

• Authorize: https://api.whenwiz.com/oauth/mcp/authorize opens the sign-in page on https://whenwiz.com
• Token: https://api.whenwiz.com/oauth/mcp/token
• Register: https://api.whenwiz.com/oauth/mcp/register

Registration is dynamic. Clients are public: PKCE S256 is required, and the token auth method is none. The scope is countdowns. Access tokens last one hour and start with wwa_. Refresh tokens start with wwr_ and rotate. API keys start with wwk_ and last until you revoke them. Tokens are stored only as hashes and are not accepted in a query string.

The consent page asks you to allow the assistant to create, change, and delete your countdowns. Deny sends the assistant back without a code.