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.
| Tool | Same as | Required scope |
|---|---|---|
list_work_periods | GET /api/v1/work-periods | time-entries:read |
list_absences | GET /api/v1/absences | absences:read |
list_employees | GET /api/v1/employees | employees:read |
list_employee_custom_fields | GET /api/v1/employees/custom-fields | employees:read |
list_projects | GET /api/v1/projects | projects:read |
list_project_custom_fields | GET /api/v1/projects/custom-fields | projects:read |
list_customers | GET /api/v1/customers | customers:read |
list_customer_custom_fields | GET /api/v1/customers/custom-fields | customers: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 plainabsent. list_work_periodsandlist_absencesrequire afrom/torange of at most 366 days.- Employees, projects and customers carry
customFields, keyed by field id. Thelist_*_custom_fieldstools 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_requiredor429 rate_limitedwithRetry-After. The server never asks the client to start an OAuth flow. - Inside a tool call,
scope_missing,validation_failedandnot_foundcome back as a tool result withisError: true. Its text is the same problem JSON, so the assistant can correct its arguments. - Every request to
/api/mcpcounts 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.