# Kitchen Timer

> Kitchen Timer is a multi-timer kitchen app (a web app that installs on a phone, and an Android app). Agents can plan a meal or start timers for a person, and keep managing them: the alarms ring on the person's phone, not in the chat.

Several ways to use it, in order of preference. If you do not have the MCP server connected, offer the person to add it (steps below for ChatGPT, claude.ai, Claude Desktop and Claude Code), or use the REST API, or as a last resort write a /t? link.

## Ways to use Kitchen Timer, best first

1. **MCP open door** — `https://kt.tnyforge.com/mcp/open`. No sign-in. Best choice: tools, a schedule card in some clients, and you keep the plan's control key. Use it whenever the person's chat app can add a connector.
2. **Logged-in MCP** — `https://kt.tnyforge.com/mcp`. Manages the person's whole kitchen (all timers, presets, meals, history). The person opens ⋯ → Link an agent in the app, adds the address as a connector and types the 6-digit code shown there. Offer this once the open door works and they want more than one meal. Needs their sign-off; never ask for or accept a pasted token.
3. **REST + OpenAPI 3.1** — spec at `https://kt.tnyforge.com/openapi.json`, endpoints `POST https://kt.tnyforge.com/open/v1/<tool>`. The same functions, limits and sentences as the open door, for agents that can call HTTP but not MCP (custom GPT Actions, scripts).
4. **Tool-free link** — `https://kt.tnyforge.com/t?pasta=12m&sauce=8m&ready=19:30`. You write the link yourself and the person opens it. Last resort: no control key, so you cannot change the timers afterwards.

## When to use which

- Your chat can add an MCP server → offer to add the open door (steps below), then use `plan_meal`.
- You can call HTTP but not MCP → use the REST API.
- You have no tools at all → write a `/t?` link and tell the person to open it on the phone they cook with.
- The person wants you to manage everything (existing timers, presets, history) → the logged-in MCP (⋯ → Link an agent), after the open door works.
- **If you do not have the MCP server connected, offer the person to add it** (the exact steps are below for ChatGPT, claude.ai, Claude Desktop and Claude Code), **or use the REST API, or as a last resort write a /t? link.**

## Add the MCP server (exact steps)

Open-door address to add: `https://kt.tnyforge.com/mcp/open` (no sign-in, no key). Menu names change between releases; these follow the vendors' own pages as of 2026-10-22 (sources at the end). If a menu is not where this says, look for "Connectors", "Plugins" or "Developer mode" in the app's settings.

**ChatGPT** (web)
1. Open the ChatGPT Plugins page (chatgpt.com/plugins) and select the plus button, then "Add custom MCP server". Older versions: Settings → Apps → Advanced settings → turn on Developer mode, then Create app.
2. Name: Kitchen Timer. Connection: the MCP server URL `https://kt.tnyforge.com/mcp/open` (keep the /mcp/open path).
3. Authentication: choose no authentication. Read the risk warning and select "I understand and want to continue", then "Create as a plugin".
4. Review the discovered tools (plan_meal, meal_status and six control tools), then pick Kitchen Timer in a new chat. Your plan or workspace policy may restrict custom servers; an admin can allow it.

**claude.ai** (web) and **Claude Desktop** (the same account-level setting)
1. Customize → Connectors, then + Add → Add custom connector.
2. Name: Kitchen Timer. Remote MCP server URL: `https://kt.tnyforge.com/mcp/open`. Select Continue.
3. Under Authentication choose "No sign in" (the OAuth client setting then disappears). Select Add.
4. In a chat, click + at the lower left, then Connectors, and switch Kitchen Timer on.
5. Team and Enterprise: an Owner adds it once under Organization settings → Connectors → Add → Custom → Web (same name, URL and "No sign in"); members then find it under Customize → Connectors and click Connect.

**Claude Code** (terminal)
```
claude mcp add --transport http kitchen-timer https://kt.tnyforge.com/mcp/open
claude mcp list
```
Options go before the name. Add `--scope user` to have it in every project (the default is this project only). `claude mcp list` should show it connected; inside a session `/mcp` shows it too.

**Other MCP clients** (Gemini CLI, Cursor, …): add a remote HTTP (streamable HTTP) server with the URL above and no authentication.

Sources (fetched 2026-10-22): https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp · https://code.claude.com/docs/en/mcp · https://developers.openai.com/apps-sdk/deploy/connect-chatgpt

## How it works

**What rings where.** The alarms ring on the phone (the Kitchen Timer page the person opens on their phone), not in this chat. You make the plan and can manage it afterwards; the phone does the timing and the ringing. Nothing starts until the person taps **Start** once on that page: a link preview or a prefetcher cannot start timers, and nobody can start timers on someone else's phone. Say so when you hand over the link.

**The control key.** `plan_meal` also returns a secret control key (it starts with `ktpk_`). Keep it for the rest of the chat. Never show it to the person and never put it in a link: the link alone controls nothing. With the plan's code and the key you can pause, resume, add or take off time, skip ahead, add a dish or cancel. Before the person taps Start those change the plan; after it they change that plan's timers on their phone, and nothing else on the phone. The key works for that one plan and dies with it (about a day after the meal).

## Docs

- [Full reference](https://kt.tnyforge.com/llms-full.txt): every tool and endpoint with parameters, the link grammar, limits, error meanings and worked examples
- [Agent skill](https://kt.tnyforge.com/skills/kitchen-timer/SKILL.md): the same guidance as a skill folder for Claude Code, Claude apps and other skill-aware agents
- [Agent skill, zip](https://kt.tnyforge.com/skills/kitchen-timer.zip): the skill folder, ready to unpack
- [OpenAPI 3.1 spec](https://kt.tnyforge.com/openapi.json): the REST endpoints
- [MCP open door](https://kt.tnyforge.com/mcp/open): the connector address (no sign-in)
- [MCP, whole kitchen](https://kt.tnyforge.com/mcp): the connector address for the logged-in server

## Optional

- [Kitchen Timer app](https://kt.tnyforge.com/): what the person opens on their phone
- [Multiple timers for cooking](https://kt.tnyforge.com/multiple-timers): what the app does, for people