MCP connection

Use https://mcp.vesta.services/mcp to connect an MCP client to Vesta, including Vesta Time data. Authentication uses your Vesta account and OAuth consent in your browser. The same server serves all employers; select the employer when authorizing access.

ChatGPT and Claude

In ChatGPT, open Plugins > + > Add custom MCP server, enter the Vesta URL and select OAuth. Create the plugin, install it from your personal plugins, then invoke it with @ in a chat. Workspace restrictions apply. See OpenAI’s connection guide.

In Claude, open Customize > Connectors > + Add > Add custom connector. Enter the Vesta URL, choose sign-in and automatic OAuth registration, then connect. For a managed workspace, its owner may need to add the connector first. See Claude’s connection guide.

These are custom connections. A public directory listing requires separate publisher review and publication; this guide does not establish that Vesta is already listed.

Connect with read-only access

1. Enable Vesta AI for the employer and your account, and check that your role can read the required data.
2. Add a remote HTTP MCP server in your client with the URL above. The client must support MCP OAuth discovery and browser authorization.
3. Sign in on Vesta’s authorization page. Never paste your Vesta password into the client or a chat.
4. Select only the employer you want to share. Reauthorizing the same OAuth client replaces its employer selection. Simultaneous isolated connections require distinct OAuth client registrations, if your client supports them; use separate customer API integrations for unattended access per employer.
5. Each selected employer starts with read-only access. Use Adjust permissions on that employer to choose its permissions independently. Select only read permissions: People to resolve employees, Planning for shifts and availability, Worked hours for worked time, and Labour cost for employer-cost reporting. Do not select write permissions.
6. Complete consent and refresh the client’s tool list.

Your role, the employer’s enabled modules and the consent grant all limit access. Consent cannot give you a permission your Vesta account does not have. Reading aggregated employer costs requires employer-cost-read permission (laborcost.read) as well as the Labour cost grant. Individual wage rates remain unavailable through MCP. An existing connection does not automatically receive newly added scopes: authorize again to add Labour cost.

Permissions are enforced separately for each employer. Write access for one employer never permits changes at another. The client may list a tool available for another selected employer; calling it still requires permission for the employer named in the request.

A read-only grant cannot create, update or delete data. With write permissions, reversible actions such as editing draft shifts can run immediately. Consequential actions, such as publishing planning, require separate confirmation in Vesta.

Read reporting data

Question	Tool	Read grant
Shifts per employee and day	get_planning	Planning
Availability per employee and day	get_availability	Planning
Worked time per employee and day	list_time_entries	Worked hours
Planned and actual cost by statute, team or task, per day or month	get_labor_cost_report	Labour cost

Pass employerUniqueCode, from and to to each tool. Cost reporting also accepts groupBy (Statute, Team, Task) and granularity (Day, Month), for up to 93 inclusive days. Ask for a full calendar month explicitly when you need monthly totals.

Availability accepts offset and limit (1 to 100, default 100); follow the returned next offset. Its range is at most 42 inclusive days. Missing availability is unknown, not a refusal to work. Time entries use offset and limit (default 50, maximum 100); fetch every page before summing completed entries. Planning includes Concept and Published shifts over at most 42 inclusive days. The planning view is bounded; narrow by employee or establishment when it reports partial output, or use the paginated customer API for a full published-shift export.

The customer API reporting guide explains the shared cost response: draft planning is included, running actuals are measured at asOf, absences are excluded, and unknown or estimated costs must remain visible. This is operational cost, not final payroll.

MCP and the customer API

MCP uses a personal OAuth connection. For unattended reporting from your server, use the customer API: its client credentials belong to exactly one employer and its scopes are read-only. Customer API tokens and MCP tokens are separate and cannot be exchanged or reused across the two services.

Manage access

Open Settings > Account > Connections in Vesta to review the permissions and employers of a connection or revoke it. Revocation is checked on subsequent requests. If the connection is refused, check your role, the selected employer, the employer’s product modules and Vesta AI settings before reconnecting.

Connection checks

The MCP host exposes OAuth discovery at https://mcp.vesta.services/.well-known/oauth-authorization-server and protected-resource metadata at https://mcp.vesta.services/.well-known/oauth-protected-resource/mcp.

On 13 October 2026, both discovery endpoints answered successfully. The MCP endpoint advertised POST support; opening /mcp directly in a browser can return 405 Method Not Allowed. An unauthenticated initialization POST returned 401 with OAuth discovery in WWW-Authenticate. This verifies public reachability and the authentication challenge, not an authenticated employer session. To verify your connection, authorize it and ask the client to list tools, then read a small date range for your employer.

If tools are missing, inspect the connection’s read permissions and your live Vesta permissions. If authorization was revoked or expired, reconnect. Never send access tokens or client secrets to support; share the error and request identifier instead.