MCP

`findtime.io`
MCP Docs for Apps, IDEs, and Agents

Install the published @findtime/mcp-server MCP server in Cursor, Codex, or Claude and call the same production-backed time intelligence surface that powers the Time API and findtime.io.

This page covers installation, verification, and troubleshooting for Cursor, Codex, and Claude, plus the current MCP tool surface and recommended smoke tests.

Distribution: Install from npm, inspect the source on GitHub, or open the public listing in the Official MCP Registry.

Production parity

The MCP server proxies time-api.findtime.io directly so apps and agents stay on one truth surface.

Published install path

Use npx -y @findtime/mcp-server in client config. A repo checkout is not required.

Agent-native tools

The tool surface includes a natural-language time question tool plus current time, DST, conversion, overlap, meeting finding, and deterministic location search.

Debuggable

We document the config files, exact prompts, and startup logs that mattered when things failed.

MCP

Parity with `findtime.io` API

The MCP server is a thin adapter over the production Time API. Current time, DST, conversion, overlap, meeting search, and location resolution should return the same answers through MCP and the API for the same inputs.

Expect the following:

MCP results should match the live API for the same inputs.
A working installation should call the MCP tool directly.
If MCP startup fails, fix the client configuration before trusting any fallback output.

MCP

Behavior and retry rules

MCP returns the API payload plus a small amount of adapter metadata so agents can retry deterministically instead of guessing.

What to expect:

search_timezones treats countryCode as a ranking hint. When you supply a hint, the MCP result includes primaryMatch and countryFilteredResults so agents do not assume every returned row matches the hint.
answer_time_question is the preferred default for natural-language agent prompts, especially messy prompts with relative dates such as tomorrow, next Friday, Tuesday, or this weekend. If the caller already has structured parameters and knows the intent, the narrower tools are still available.
convert_time accepts explicit ISO dates and simple human day words in the time field, such as 3pm Tuesday or 3pm thur. Scheduling tools such as get_overlap_hours and find_meeting_time accept simple human values in date, such as Thursday, tomorrow, or next Friday, resolved relative to the first location timezone.
get_current_time is best with a city, exact timezone, or a location resolved from search_timezones. Exact country-name inputs now resolve directly for single-zone countries and return explicit ambiguity for countries with multiple timezones.
Abbreviations such as IST are often ambiguous. Use search_timezones first or pair the query with a region or country when you need one deterministic answer.
MCP tool errors keep a consistent shape: HTTP status, request URL, and the parsed API error body are included in the structured result so the client can surface the exact failure.

MCP

Per-call end-user attribution

Multi-user MCP hosts such as Slack, Discord, Teams, and internal company bots can run one long-lived @findtime/mcp-server process while still attributing each Time API call to the end-user who triggered it.

How it works:

Add optional _endUserId metadata inside the MCP tool call arguments object.
The MCP server strips _endUserId from the tool parameters and forwards it only as X-Findtime-End-User-ID to time-api.findtime.io.
Missing, null, or empty values are treated as absent, so existing single-user installs keep the same install-level attribution behavior.
The value must be a string, at most 256 characters, and cannot contain control characters such as carriage returns or newlines.

Privacy contract: _endUserId should be an opaque, non-PII token generated by the host, typically a SHA-256 hash of the platform user ID truncated to 16-32 hex characters. Do not send raw emails, names, Slack IDs, Discord IDs, Teams IDs, or other personally identifiable values.

Host-injected attribution

await client.callTool({
  name: "get_current_time",
  arguments: {
    city: "Tokyo",
    _endUserId: "a3f2c1d4e5b6c7d8"
  }
});

MCP

Setup by client

Select your client below. The config snippet, verification prompt, and troubleshooting guidance update with the selected platform.

Before you start:

Create a developer key first from /developers/keys/.
You usually do not need to run a terminal command during setup. The MCP client runs npx -y @findtime/mcp-server for you after you save the config and restart the client.
Install Node 20 or newer first so the client can run npx.
Use npx -y @findtime/mcp-server in the MCP config. A repo checkout is not required.
The package is published on npm and listed in the Official MCP Registry at io.github.hkchao/findtime-mcp-server.
Point the server at https://time-api.findtime.io or omit the base URL to use the default.
After changing MCP config, fully restart the client before testing again.

Active file

~/.cursor/mcp.jsonCursor

Edit this file for the selected client.

mcp.json

{
  "mcpServers": {
    "findtime": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@findtime/mcp-server"],
      "env": {
        "FINDTIME_MCP_CLIENT_TYPE": "cursor",
        "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io",
        "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY"
      }
    }
  }
}

Cursor setup checklist:

Confirm which Cursor config is active. If you already have a global MCP config, Cursor may be reading `~/.cursor/mcp.json` instead of a repo-local `.cursor/mcp.json`.
Use `npx` so Cursor installs and runs `@findtime/mcp-server` directly. A repo checkout is not required.
Keep Cursor Settings open with the Output pane visible before reconnecting so you can watch the MCP startup logs in real time.
After saving the config, reload Cursor so it recreates the stdio process with the new values.

MCP

Testing and smoke prompts

Use these prompts to verify that the client is making native MCP tool calls. If the client searches the repo or runs local Node code instead, treat that as fallback behavior and continue debugging the MCP setup.

Verification only:Use the explicit Use the findtime.io MCP tool ... phrasing during setup so you can confirm the client is calling the MCP server directly. After that succeeds, switch back to normal natural-language prompts.

Cursor smoke test

Use the findtime.io MCP tool answer_time_question for "what is the IANA timezone for San Francisco?"

Additional smoke tests

Use the findtime.io MCP tool answer_time_question for "what is the IANA timezone for San Francisco?"
Use the findtime.io MCP tool answer_time_question for "3pm PST to London".
Use the findtime.io MCP tool answer_time_question for "convert 3pm next Tuesday in New York to London and Tokyo".
Use the findtime.io MCP tool get_current_time for city "Tokyo" with countryCode "JP".
Use the findtime.io MCP tool get_api_diagnostics.
Use the findtime.io MCP tool search_timezones for "Victoria" with countryCode "CA".
Use the findtime.io MCP tool get_dst_schedule for timezone "America/New_York".
Use the findtime.io MCP tool get_dst_schedule for timezone "Europe/London" with year 2026.
Use the findtime.io MCP tool get_dst_schedule for timezone "Europe/London" with at "2025-03-22T12:00:00Z".
Use the findtime.io MCP tool convert_time from "New York" to ["London","Tokyo"] at time "9:00 AM" on date "2026-03-10".
Use the findtime.io MCP tool find_meeting_time for locations ["Tokyo","Cairo","New York"] with countryCodes ["JP","EG","US"] on date "2026-03-10".

Recommended sequence:

Start with an explicit tool-call prompt such as Use the findtime.io MCP tool answer_time_question for "what is the IANA timezone for San Francisco?"
Once that works, test answer_time_question with normal prompts such as Best meeting time between New York, Sydney, and Mumbai?, Does Cairo observe DST?, or What does CST mean?
Cursor: the Output pane should show a successful stdio connection and the chat should call a findtime MCP tool.
Codex and Claude: the chat should call the MCP tool directly and should not fall back to repo search or local Node execution.

MCP

Troubleshooting

Use this section to diagnose startup failures, missing tools, auth errors, and false-positive fallback behavior.

Common setup issues:

Editing the wrong config file. Each client has its own MCP config source.
Leaving an old MCP server path in the config after moving the implementation to a new repo location.
Forgetting to provide a developer API key in the MCP client env.
Counting a local fallback execution as proof that MCP was working.
Restarting only the thread instead of the full client after changing MCP config.

Symptom	Likely cause	What to do
Startup timeout in Cursor	Stale config, first-run install issue, or the wrong command	Open Output, verify the command is `npx -y @findtime/mcp-server`, then reload Cursor after fixing the config.
`initialize response` failure in Codex	Outdated MCP transport behavior or stale app process	Update to the latest server code and fully quit and relaunch Codex.
Tool call returns 401	Missing or wrong API key	Set `FINDTIME_TIME_API_KEY` to a live developer key.
The model searched the repo and ran local JS	MCP was still unavailable	Treat that as fallback behavior, not success. Fix MCP first, then retry with a fresh thread.
Behavior seems stale even though MCP is connected	The client may still be running an older MCP package, or the latest version lookup may have failed	Run `get_api_diagnostics`. Check `mcpInstallMode` first, then compare `mcpVersion` and `mcpLatestVersion`. If the latest check fails, follow the returned npm or Official MCP Registry links to verify the newest published version manually.

Expected Cursor success logs

2026-03-21 14:33:22.064 [info] Starting new stdio process with command: npx -y @findtime/mcp-server
2026-03-21 14:33:22.123 [info] Successfully connected to stdio server
2026-03-21 14:33:22.123 [info] Storing stdio client: user-findtime
2026-03-21 14:33:22.123 [info] [MCP Allowlist] Creating adapter with serverName="findtime", identifier="user-findtime"
2026-03-21 14:33:22.123 [info] CreateClient completed, server stored: true

Cursor gotchas:

Editing the wrong file is the #1 trap. Verify whether Cursor is using the global config or a repo-local config.
If the Output pane shows a timeout during startup, check that the command is `npx -y @findtime/mcp-server` and that Cursor reloaded after the edit.
If the server connects but tool calls return 401, the missing piece is usually `FINDTIME_TIME_API_KEY`.

MCP

MCP tool surface

These tools are available through the findtime MCP server. Use them directly from your client once setup is complete.

Tool	Parameters	Best for	Why it matters
`answer_time_question`	Required `query` Optional `userTimezonelocalenowdate`	Natural-language time questions	Preferred default for natural-language agent prompts, especially when the user says "tomorrow", "next Friday", "Tuesday", "this weekend", or another relative date. Classifies current time, conversion, DST, overlap, meeting, abbreviation, and IANA timezone questions and returns structured clarification when input is ambiguous.
`time_snapshot`	Required `query or locations` Optional `countryCode or countryCodesincludeTransitions`	One-call time intelligence	Best default tool when you want packaged location, timezone, current time, DST, and optional transitions. Batch calls can return per-location status with retry-friendly suggestedQuery and suggestedId values instead of failing all at once.
`get_current_time`	Required `city or query` Optional `countryCode`	Single-location time lookups	Fastest current-time check when you already know the city or timezone you want and there is no natural-language date qualifier. Exact country-name queries resolve directly for single-zone countries and return explicit ambiguity for multi-zone countries.
`get_api_diagnostics`	none	Version and environment debugging	Confirms the running MCP version, reports whether the client is using a repo checkout or npm package install, checks the latest published MCP version when available, and returns the active API base URL, auth state, and health result.
`get_dst_schedule`	Required `city, query, or timezone` Optional `countryCodeatyear`	DST truth	Use this when the question is specifically about DST status, last transition, next transition, or a calendar-year view and the date context is already structured. Route relative-date prompts through answer_time_question first.
`convert_time`	Required `fromtotimedate` Optional `fromCountryCodetoCountryCodes`	One-to-many conversion	Convert a source local time into one or more target locations on an explicit ISO date, for the current moment, or from a simple human time such as "3pm Tuesday". Route messier raw prompts through answer_time_question so the answer layer can classify and resolve them before conversion.
`get_overlap_hours`	Required `locationsdate` Optional `countryCodes`	Scheduling workflows	Returns shared overlap across locations instead of leaving the caller to compute it manually. Use answer_time_question first when the user gives a relative date such as "this week", "tomorrow", or "next Friday".
`find_meeting_time`	Required `locations` Optional `countryCodesdate`	Agent and meeting planning	Returns ranked meeting suggestions and a planner link back into findtime.io. Use answer_time_question first when the user gives a relative date such as "next week" or "Friday".
`search_timezones`	Required `query` Optional `countryCodelimit`	Ambiguity handling	Resolve places like Victoria or timezone abbreviations like IST before a later tool call. countryCode is a ranking hint, not a strict result filter.
`get_location_by_id`	Required `id`	Deterministic hydration	Hydrate a stable `findtime:` location id when you want exact repeatability across calls.

findtime.ioMCP Docs for Apps, IDEs, and Agents