TaskTime Pro MCP Quickstart

1. Discover TaskTime Pro

Start from llms.txt or /.well-known/tasktime-agent.json. The manifest identifies TaskTime Pro as a local-first task, time tracking, expense, invoicing, and reporting app with a local MCP bridge.

2. Install The Host Integration

OpenClaw users should install the native plugin so the supervised Gateway owns one bridge across ordinary turns:

openclaw plugins install @tasktimepro/openclaw
openclaw gateway restart
openclaw plugins inspect tasktime --runtime

Generic MCP and Claude Code hosts continue to launch the packaged bridge over stdio. It reads MCP JSON-RPC from stdin, writes responses to stdout, and keeps short-lived pairing details on the interactive setup channel.

tasktime-agent-bridge --app-url https://app.tasktime.pro

The bridge binary package is @tasktimepro/agent-bridge. Claude Code users can use the TaskTime Pro Claude plugin. The standalone ClawHub skill and generic bridge remain portable advanced paths, but they are not the recommended complete OpenClaw installation. For local development, point --app-url at the local app origin, usually http://localhost:3101. The bridge prints a launch URL for /account?section=agent with the endpoint, pairing ID, and pairing code already filled in. Managed bundles should also pass a stable --agent-id, a user-facing --agent-label, and a --status-file path for non-secret endpoint/process discovery. Obtain pairing credentials from get_pairing_status, not from the persistent status file.

3. Pair The Browser App

TaskTime Pro must be open in a browser tab. The user approves the local bridge in Account > Agent Access. First-use access is explicit; localhost discovery is not treated as permission.

• The app-session WebSocket target must be loopback, such as ws://127.0.0.1:39123/tasktime-agent.
• The pairing ID and pairing code are time-limited and single-use.
• The WebSocket port is dynamic; pair to the active bridge process, not an example or stale terminal bridge.
• Stable agent identity comes from --agent-id, not from the localhost port.
• The paired browser app becomes the authoritative app session for command execution.
• Refreshing the tab resumes from current-tab storage; same-profile reopen uses browser proof of possession.
• A Gateway/bridge restart, explicit disconnect, revoke, disable, forget, or expiry requires pairing again.

4. List Tools

After the bridge starts, an MCP host can initialize and list scoped tools. The public reference at /agents/tools/ and machine-readable catalog at /agents/mcp-tools.json come from the same MCP tool definitions used by the bridge. Setup tools such as get_pairing_status and refresh_pairing are intentionally available before the browser app is paired.

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

5. Call A Tool

Use tools/call with a supported TaskTime Pro tool name and JSON arguments. The bridge forwards the request to the paired browser app, which returns structured results.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_projects",
    "arguments": {}
  }
}

Recovery Behavior

If a tool call fails because no authoritative TaskTime Pro app session is paired, the MCP error includes a recovery hint with action: "launch_tasktime" and reason: "authoritative_app_session_required". Agent hosts should guide the user to launch and pair TaskTime Pro, then retry the tool call. First call get_pairing_status; if its pairing has expired or was used by a stale attempt, call refresh_pairing and open the returned launch URL.