AI assistants and agents

Use eTime from your AI assistant

Connect Claude, Codex, Cursor, GitHub Copilot, Gemini or any agent that speaks MCP to eTime. Ask about rosters in plain words, find cover for a sick call, and check a change against your rules before you make it.

Server URL: https://api.etime.my/mcp
Transport: Streamable HTTP
Auth: Authorization: Bearer etk_…

On this page

What is MCP?
Connect
Tools
Things to ask
Keys and safety
Technical details

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants use tools in other apps. eTime's MCP server gives your assistant a small set of tools, such as "get a week of a roster" or "find cover for this shift". The assistant decides when to use them while you chat, and it only ever sees what you could see in eTime yourself.

Connect

First make an API key in eTime under Account → API keys. Start with a Read key; choose Read and write only if you want the assistant to change shifts.

Claude Code

Put your key in your shell profile as ETIME_KEY, then run this once in a terminal:

Shell

# Once, in ~/.zshrc or ~/.bashrc:  export ETIME_KEY="etk_live_…"
claude mcp add --transport http etime https://api.etime.my/mcp \
  --header "Authorization: Bearer $ETIME_KEY"

Then ask about your roster. /mcp shows the connection and its tools.

Claude Desktop and claude.ai

Open Customize → Connectors, choose Add custom connector, name it eTime and paste the server URL. Under Request headers, add Authorization with the value Bearer etk_live_…. On Team and Enterprise plans an owner adds it under Organization settings → Connectors, and everyone then uses that one key.

Or with the config file and mcp-remote

Open Settings → Developer → Edit config and add eTime to claude_desktop_config.json (needs Node.js), then restart Claude Desktop.

claude_desktop_config.json

{
  "mcpServers": {
    "etime": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.etime.my/mcp", "--header", "Authorization:${ETIME_AUTH}"],
      "env": { "ETIME_AUTH": "Bearer etk_live_…" }
    }
  }
}

Codex (OpenAI)

Add eTime to ~/.codex/config.toml (or a project's .codex/config.toml). Codex sends the key from an environment variable, so it never sits in the file:

config.toml

# ~/.codex/config.toml
[mcp_servers.etime]
url = "https://api.etime.my/mcp"
bearer_token_env_var = "ETIME_KEY"

Shell

export ETIME_KEY="etk_live_…"

If ETIME_KEY isn't set, Codex connects without a key and eTime says no. Set it in your shell profile.

Cursor

Add eTime to .cursor/mcp.json in a project, or ~/.cursor/mcp.json for all of them. Cursor fills in ${env:ETIME_KEY} from your environment:

mcp.json

{
  "mcpServers": {
    "etime": {
      "url": "https://api.etime.my/mcp",
      "headers": { "Authorization": "Bearer ${env:ETIME_KEY}" }
    }
  }
}

VS Code and GitHub Copilot

Add eTime to .vscode/mcp.json. VS Code asks for the key the first time and keeps it in its secure storage:

mcp.json

{
  "servers": {
    "etime": {
      "type": "http",
      "url": "https://api.etime.my/mcp",
      "headers": { "Authorization": "Bearer ${input:etime-key}" }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "etime-key", "description": "eTime API key", "password": true }
  ]
}

Gemini CLI

Add eTime to ~/.gemini/settings.json. Use httpUrl (not url, which is the older SSE transport):

settings.json

{
  "mcpServers": {
    "etime": {
      "httpUrl": "https://api.etime.my/mcp",
      "headers": { "Authorization": "Bearer etk_live_…" }
    }
  }
}

Other agents

Windsurf, Zed, Continue, your own agent built with an MCP SDK, or any client that supports a remote server over Streamable HTTP: give it the server URL and an Authorization header with your key. Look for "remote" or "HTTP" servers in its MCP settings; the file is usually shaped like this:

mcp.json

{
  "mcpServers": {
    "etime": {
      "url": "https://api.etime.my/mcp",
      "headers": { "Authorization": "Bearer etk_live_…" }
    }
  }
}

eTime's server takes an API key, not an OAuth sign-in. Apps that only connect through an OAuth sign-in (such as ChatGPT's web connectors) can't use it yet; Codex and the API work today.

Tools

Each tool does exactly what your role allows in the app, in your units. Tools that change things appear only for read-and-write keys.

whoamiRead

Who the key acts as: your name, role and workplace, and whether the key can make changes.

list_unitsRead

Your sites and units, with their ids and time zones.

list_rostersRead

Roster periods for your units, with status and version. The current one is marked.

get_weekRead

One week of a roster: who works which shift each day, and the open shifts. As a compact table and as data.

my_shiftsRead

Your own upcoming shifts, in every unit.

open_shiftsRead

Shifts nobody is on yet, and whether each has been offered to staff.

find_coverRead

Who can take an open shift, best first, with the reasons, and why the others can't. The same ranking as the app.

check_changeRead

What-if: the rules a change would break or fix and, with pay access, what it would cost. Saves nothing.

assign_shiftRead and write

Put someone on a shift. Checked against every rule, like a change in the app.

unassign_shiftRead and write

Take someone off a shift, leaving it open.

list_peopleRead

People and their roles, units and contract hours. Names are left out in ID mode.

leave_balancesRead

Holiday days left, time off in lieu and flex: yours, and the team's if you run it.

insights_summaryRead

A roster at a glance: shifts filled and open, rule breaks, planned hours and, with pay access, the cost.

Things to ask

What am I working next week?
Show me Ward 3B's roster for this week.
Which shifts are still open before Sunday?
Sam is off sick tonight. Who's the best person to cover the night shift, and why?
If I move Ingrid to Thursday's night, does that break any rules? What does it cost?
Put Ingrid on Thursday's night shift.
How many holiday days does the team have left?
Summarise this roster: what's open, and what breaks the rules?

Keys and safety

A key acts as you. The assistant sees what you see and can do what you can do, nothing more. People without pay access never get pay figures, and ID mode keeps names out.
Read keys can't change anything, whatever your role. Use one unless you want the assistant to change shifts.
Changes follow the rules. A shift change through MCP is checked against labour law, the agreement and your house rules, exactly like one in the app. It is saved as a new roster version, everyone watching sees it at once, and the history shows it as yours.
Assistants can get things wrong. Ask for a check_change first, and read what it is about to do before you say yes.
Revoke a key the moment you stop using it or think it has leaked: Account → API keys → Revoke. It stops working straight away. Owners and admins can revoke anyone's key.
Only keys work here. The MCP server never uses your sign-in cookies, so a web page can't use it on your behalf.

Technical details

The server speaks MCP over Streamable HTTP without sessions: each POST carries a JSON-RPC message and gets a JSON answer. It supports protocol versions 2025-11-25, 2025-06-18 and 2025-03-26, and the methods initialize, ping, tools/list and tools/call. Tool results come as text, and as structured data for clients on 2025-06-18 or later. Each key may make 120 requests a minute.

Shell

curl https://api.etime.my/mcp \
  -H "Authorization: Bearer $ETIME_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"my_shifts","arguments":{"days":7}}}'

Prefer plain HTTP? The same data is in the REST API.

Something unclear or missing? Email support@etime.my.