VergeHR MCP Connector

VergeHR is a complete HR system: people, leave, attendance, payroll, performance and more. The connector lets an AI app work as one person, seeing only what their role lets them see and, if they allow it, making a few safe changes. AI Apps, for Users

Connection

MCP Endpoint

https://vergehr.com/mcp

Transport

Streamable HTTP, POST only, JSON responses, stateless (no session id, no SSE). GET and DELETE return 405.

Protocol Versions

2025-11-25, 2025-06-18, 2025-03-26

Capabilities

Tools, with titles and annotations. No resources, prompts or sampling.

Who Can Connect

A VergeHR login whose role has Connect My AI Apps, in an organization that has switched AI apps on (off by default). One global address: the person signs in with their organization code.

Support

Contact · Privacy · Terms

Sign-In (OAuth 2.1)

An unauthenticated call to /mcp returns 401 with a WWW-Authenticate header that points to the discovery documents below.

Protected Resource

/.well-known/oauth-protected-resource/mcp (RFC 9728)

Authorization Server

/.well-known/oauth-authorization-server (RFC 8414)

Authorize

/oauth/authorize

Token

/oauth/token (authorization_code, refresh_token)

Registration

/oauth/register (RFC 7591)

Revocation

/oauth/revoke (RFC 7009)

PKCE

S256, required for public clients.

Resource

https://vergehr.com/mcp (RFC 8707). Tokens are bound to it.

Token Lifetimes

Access token 1 hour. Refresh token 30 days, rotated on every use; reusing an old one ends the connection. A connection lasts at most 90 days before the person approves it again.

Apps that don't register themselves can use credentials the person makes in Settings → Profile → AI Apps: a Client ID (with an optional secret; only its owner can approve it, and its return address is learned on first approval), or an access key for 30, 90 or 365 days, sent as Authorization: Bearer vha_… .

Scopes

Scope	Grants	On the Consent Page
`read`	The person's own HR details and what their role reaches.	Always granted
`sensitive`	Pay and salary figures, bank details, identity numbers, where the role already shows them.	Opt-in box, unticked
`write`	The narrow changes listed below.	Opt-in box, unticked

tools/list returns only what the connection's scopes and the person's permissions allow. No scope lets an app delete anything, change settings or permissions, create employees, run payroll, send arbitrary email or do anything in bulk.

Tools

35 tools. Every tool carries MCP annotations. Ids are whole numbers from earlier results. Dates are YYYY-MM-DD. Arguments outside a tool's schema are refused. Lists are paged, up to 100.

Tool	Scope	What It Does	Inputs
`get_my_profile`	read	Who is signed in: name, role, organization, job, manager, today's date, and how much is waiting on them.	`—`
`search_employees`	read	Search the Employee Directory, within the person's role.	`query, page, page_size`
`get_employee`	read	One colleague's Directory profile.	`employee_id`
`list_my_team`	read	The person's manager, direct reports and peers.	`—`
`get_org_chart`	read	The organization chart, within the person's role.	`page, page_size`
`list_my_leave_balances`	read	The person's leave balances.	`year`
`list_my_leave_requests`	read	The person's own leave requests.	`status, page, page_size`
`list_team_leave`	read	Who is off on which days.	`from_date, to_date, page, page_size`
`list_holidays`	read	The holidays that apply to the person.	`from_date, to_date`
`get_my_attendance`	read	The person's own timesheet.	`from_date, to_date`
`get_my_schedule`	read	The person's own published shifts.	`days, page, page_size`
`list_my_approvals`	read	Leave and attendance requests waiting on the person, and how many others.	`page, page_size`
`list_my_goals`	read	The person's own goals.	`status, page, page_size`
`list_my_reviews`	read	The person's own performance reviews.	`page, page_size`
`list_my_feedback`	read	Feedback the person received or gave.	`which, page, page_size`
`list_my_training`	read	The courses assigned to the person.	`—`
`list_my_expense_claims`	read	The person's own expense claims.	`page, page_size`
`list_my_tickets`	read	The Help Desk tickets the person raised.	`page, page_size`
`list_ticket_categories`	read	The categories a ticket can be raised under.	`—`
`list_policies`	read	Published policies, and which the person still has to acknowledge.	`page, page_size`
`get_policy`	read	One published policy's text.	`policy_id`
`list_announcements`	read	The company announcements up now.	`—`
`list_job_openings`	read	Job openings and candidate counts. Needs the recruitment permission.	`show, query, page, page_size`
`list_candidates`	read	Candidates by name and pipeline stage, no resumes or fit scores. Needs the recruitment permission.	`show, job_id, query, page, page_size`
`list_reports`	read	The reports the person may run.	`—`
`run_report`	read	Run one report, within the person's role. Reports with pay, money or identity columns need the sensitive scope.	`report_key, from_date, to_date, page, page_size`
`list_my_payslips`	sensitive	The person's own payslips.	`page, page_size`
`get_my_payslip`	sensitive	One of the person's own payslips, line by line.	`payslip_id`
`get_employee_sensitive`	sensitive	Identity numbers, masked bank details and salary, only where the role already shows them.	`employee_id`
`request_leave`	write	Ask for leave. It goes through the approval chain.	`leave_type_id, start_date, end_date, half_day, reason`
`give_feedback`	write	Give one colleague feedback. They are notified.	`employee_id, kind, text`
`add_goal_checkin`	write	Check in on a goal. Overwrites its progress and health.	`goal_id, progress, health, note`
`acknowledge_policy`	write	Record that the person read a policy.	`policy_id`
`submit_ticket`	write	Raise a Help Desk ticket. HR is notified.	`category_id, subject, text, priority`
`decide_approval`	write	Approve or reject a leave request or attendance correction waiting on the person, never their own. Nothing else can be decided.	`kind, request_id, decision, note`

Limits and Errors

120 calls a minute and 5,000 a day per connection, 240 and 15,000 per login. Over the limit, /mcp returns HTTP 429 with a JSON-RPC error.
At most 40 changes an hour and 200 a day per connection.
One JSON-RPC message per POST, at most 64 KB (HTTP 413 otherwise).
A connection that keeps making refused calls is paused for an hour. An IP that sends far more than an app needs, keeps presenting invalid tokens or keeps failing sign-in exchanges is blocked from these endpoints for an hour. Hosted agents' shared IPs aren't blocked for one connection's calls.
Tool errors come back as a normal result with isError: true and a plain-English message. An id that doesn't exist and one out of reach give the same answer.
401 invalid_token means the connection has ended: disconnected, switched off, password changed, access lost. The app should sign in again.
OAuth errors follow RFC 6749, with an error_description.

Data and Security

A connection reaches one person in one organization. Every tool runs through the module's own permission and data-scope rules; there is no cross-organization access.
Tokens and secrets are stored only as SHA-256 hashes and never appear in URLs or logs.
Every tool call is recorded where the person and their administrators can see it. The person is emailed when a new app connects.
VergeHR doesn't use connector data for advertising or to train AI models.