Connect Autonomous AI Agents to Time Doctor (MCP)

Note: Available only with BETA CUSTOMERS for now.

The AI connection (MCP) is available on all Time Doctor subscription plans and can be accessed by Owners, Admins, and Managers.

Tip: For developers building agentic software. If just connecting an AI assistant like Claude or ChatGPT, start with Connect Time Doctor to Your AI Tools instead. Access is read-only and follows the API key owner's Time Doctor role.

TL;DR

Connect agentic software to the Time Doctor AI connection (MCP) server using an API key as a bearer token, skipping the interactive setup used by desktop AI tools. The connection is read-only and inherits the exact role and data visibility of the account that created the key. This article covers connection details, security practices, a working example, and compatibility with agent frameworks.

Connecting Autonomous Agents

Pass a Time Doctor API key as a bearer token to the MCP server to connect agentic software programmatically, without the interactive setup used by desktop AI tools.

Scope access carefully. The API key carries the exact Time Doctor access of the user who created it, including their access level and the data that access level can see. Create the key from an account whose access matches what the agent actually needs, and no more. The AI connection (MCP) is read-only, so an agent can read and report data but can’t change, add, or delete anything in the workspace.

Connection Details

Server URL: https://api2.timedoctor.com/api/2.0/mcp/mcp
Auth header: x-api-key: <key> (or Authorization: Bearer <key>)
Transport: Streamable HTTP (JSON-RPC 2.0)

On your AI Connections page, click “Connect an AI Tool”, “Custom tool”, and then “Create Connection”. An API key will be displayed. For security, the key appears only once, at creation. Revoke it anytime from the same screen.

Keep API Keys Out of Code

Do not embed API keys in code or commit them to source control. Provide the key to the agent through a secrets vault or an environment variable, and rotate it if it is ever exposed. Anyone with the key has the same read access to the Time Doctor data as the person who created it, so treat it like a password.

Example: Call a Tool

List the Tools
List the tools the key can access:

Call a Tool
Call a tool. This example requests a time summary for a date range:

curl https://api2.timedoctor.com/api/2.0/mcp/mcp \
-H "Content-Type: application/json" \
-H "x-api-key: $TIMEDOCTOR_API_KEY" \
-d '{
   "jsonrpc": "2.0",
   "method": "tools/call",
   "params": {
"name": "td_get_time_summary",
"arguments": { "from": "2026-07-01", "to": "2026-07-31" }
   },
   "id": 1
}'

The key is read from the TIMEDOCTOR_API_KEY environment variable rather than pasted into the command, so it never appears in shell history.

Discovering Available Tools

The tool list is discoverable and always current. Call tools/list on the MCP endpoint to retrieve the tools available to the connection key, each with its full parameter schema and a description covering when to use it, when not to, call order, and how it relates to other tools. Read these descriptions before wiring up calls; they serve as the authoritative reference.

A chat client (Claude, ChatGPT) is not required for this step. An authenticated request to the MCP endpoint is sufficient — see the curl example above.

Available tools depend on plan and role. tools/list returns only the tools a connection is entitled to, so the set reflects the Time Doctor pricing plan and add-ons in place, plus the role of the key's owner. Two keys on different plans can return different tool sets; this is expected behavior. If an expected tool is missing, check for the plan or add-on that includes that data (for example, Unusual Activity Report or meeting insights).

Use With Agent Frameworks

The same server URL and header work with any framework that supports remote MCP over Streamable HTTP with header-based auth. For example, register Time Doctor as a remote MCP server with OpenAI's Responses API by passing the server URL and API key in the request's MCP tool configuration. See Connect a Custom AI Tool to Time Doctor for the generic configuration pattern and the field-name variations across different tools.

Timezones and Data Limits

For accurate results, pass an explicit timezone (IANA format, e.g., Asia/Manila) on range-based calls, and keep requests within the limits: up to 200 group members and one year per request. See Getting Started: What to Ask Your Time Doctor AI Connection for the full notes on limits and batching large analyses.

Should there be any inconsistencies or concerns regarding the article, contact support@timedoctor.com for prompt assistance.