Skip to Content
Z8Z8 Docs

MCP Server

Let AI assistants read your organization's Z8 data through the Model Context Protocol

Z8 offers the Public API as an MCP server, so AI assistants and agents can read your organization's data as tools. It is read-only and serves exactly what the same API key could read through /api/v1: the same rows, fields, scopes, rate limits and errors.

Server URL and authentication

  • URL: https://ui.z8-time.app/api/mcp
  • Transport: Streamable HTTP. The server is stateless, so it keeps no session between requests.
  • Authentication: an organization API key, sent as Authorization: Bearer z8_org…. Create one under Settings → Enterprise → API Keys (see API Keys).

Use a dedicated key for MCP

Whatever a tool returns is sent to your MCP client's LLM provider. Create a separate key for MCP with only the scopes the assistant needs, and without absences:read-health and custom-fields:read-restricted, so health detail and the custom fields only managers or admins see never leave Z8.

Tools

The assistant sees only the tools its key's scopes allow. Calling a tool without its scope returns a tool error with scope_missing.

ToolSame asRequired scope
list_work_periodsGET /api/v1/work-periodstime-entries:read
list_absencesGET /api/v1/absencesabsences:read
list_employeesGET /api/v1/employeesemployees:read
list_employee_custom_fieldsGET /api/v1/employees/custom-fieldsemployees:read
list_projectsGET /api/v1/projectsprojects:read
list_project_custom_fieldsGET /api/v1/projects/custom-fieldsprojects:read
list_customersGET /api/v1/customerscustomers:read
list_customer_custom_fieldsGET /api/v1/customers/custom-fieldscustomers:read

custom-fields:read-restricted adds no tool of its own: it only widens which custom fields the employee, project and customer tools return.

Each tool takes its endpoint's query parameters as arguments and returns the same page as structured content: { "data": [...], "nextCursor": "..." }, plus asOf for employees, projects and customers. To read the next page, the assistant passes nextCursor back as cursor.

The data rules are the same as for the API, and each tool's description repeats them for the assistant:

  • Work periods are UTC instants, each with the UTC offset where it was recorded. Running work has no end.
  • Absences are local calendar dates with an optional half day. Without absences:read-health, a sick absence is plain absent.
  • list_work_periods and list_absences require a from/to range of at most 366 days.
  • Employees, projects and customers carry customFields, keyed by field id. The list_*_custom_fields tools name each field; a select value carries its option's label inline.
  • Custom field values are read as of asOf, today in your organization's timezone unless the assistant passes a date. A tracked field can hold another value on another date.
  • Without custom-fields:read-restricted, only the custom fields every member sees are returned, in the values and in the field lists.

Set up a client

Claude Code

claude mcp add --transport http z8 https://ui.z8-time.app/api/mcp \
  --header "Authorization: Bearer z8_org…"

Cursor

Add the server to .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "z8": {
      "url": "https://ui.z8-time.app/api/mcp",
      "headers": { "Authorization": "Bearer z8_org…" }
    }
  }
}

Other clients

Any MCP client that connects to a Streamable HTTP server with a custom header works. Configure:

  • the URL https://ui.z8-time.app/api/mcp;
  • the header Authorization: Bearer z8_org….

Clients that speak an older protocol revision (2025-era, starting with initialize) are served statelessly too.

Web connectors that need OAuth cannot connect yet

The server accepts API keys only. Connectors that require an OAuth sign-in, such as custom connectors on claude.ai or in ChatGPT, cannot connect yet.

Errors, rate limits and the request log

  • Before any tool runs, a request is refused with a plain HTTP status and problem JSON, exactly as on /api/v1: 401 invalid_key, 402 billing_required or 429 rate_limited with Retry-After. The server never asks the client to start an OAuth flow.
  • Inside a tool call, scope_missing, validation_failed and not_found come back as a tool result with isError: true. Its text is the same problem JSON, so the assistant can correct its arguments.
  • Every request to /api/mcp counts against the key's limit and your organization's limit, the same budget as /api/v1.
  • Each tool call appears in the key's recent requests with the channel MCP. Connecting and listing tools read no data and are not logged.

On this page