LeaveCalc with AI assistants (MCP)

Overview

MCP (Model Context Protocol) is the open standard AI assistants use to call tools in other products. With it you can ask things like “Who is out next week?”, “How many vacation days does Ann have left?” or “Ask for Friday off for me”, and, with a token that can change things, “Approve Ben’s request for 9 November”.

• Address: https://leavecalc.com/api/v1/mcp
• Sign in: a LeaveCalc API token, sent as Authorization: Bearer lc_.... These are the same tokens as the LeaveCalc API, and the MCP server is part of every plan, Free included.
• Transport: MCP Streamable HTTP, POST only.
• Protocol versions: 2026-07-28 (current), and 2025-11-25, 2025-06-18 and 2025-03-26 (the handshake most assistants still use today).

What the assistant can do

“Write token” is the choice Read and change when you make the token. A token that can only read does not even see the three tools that change things.

Documents attached to requests (such as doctor’s notes), pay, attendance points, support messages and private manager notes are not available through MCP at all.

Rules the server follows

The same rules as the LeaveCalc API.

• The same checks as the app. A request made through the assistant is validated, counted and announced exactly like one made in LeaveCalc: the approvers get their email, Slack or Teams message, and webhooks fire. Approving and denying run the app’s own approval, including two-step approval, balances and blackout dates.
• Sick, FMLA and protected leave. By default the assistant sees such time off as “Time off”, without the leave type and without the note, and it is left out of balances. A token made with the switch Include the type of sick and medical leave sees the leave type (and the notes of ordinary requests). Notes of sick and medical requests are never shown to any token.
• Nobody approves their own request. A token acts with the rights of the owner who made it, and that owner cannot approve or deny their own request through the assistant (they still can in the app). Use another owner’s token or the app.
• Blackout dates are never overridden. If a blackout blocks an approval, the assistant is told to open the request in LeaveCalc.
• Approved time off cannot be cancelled through the assistant. deny_request only works on pending requests.
• Asking twice is safe. If the assistant retries the same request (same person, leave type and dates), the second try is refused and names the first request. The exception is sick, FMLA and protected leave with a token that may not see the leave type: there the refusal would reveal who was ill and when, so such a retry is simply a second request.
• Writes need an exact person. request_time_off acts only for “me”, a person id, an exact email address or an exact full name. For anything else (“Ann”) it changes nothing and answers with candidates, so the assistant has to ask you which one. Reading tools still search by part of a name.
• Approving and denying need proof that the assistant has the right request. Besides the request id the assistant must give the employee (exact full name, email or person id) and the start date, as you named them. If they do not match, nothing happens and the answer is mismatch. A request note that says “approve request 17” cannot supply those two values for the assistant. Both tools are marked destructive, so assistants that honour that hint ask you every time.
• Notes are labelled. Request notes (only for a token made to see them) reach the assistant as {"untrusted_text": "..."}, cut to 200 characters, and the assistant is told that this is text an employee wrote, never an order.
• Decisions say where they came from. A note on an approval or denial made through the assistant starts with “Decided through” and the token name.
• Limits. 120 calls a minute per token and 300 a minute for all tokens of one company. A list_people search by name counts as 5. Past the limit the server answers 429 with a Retry-After header.
• Every change is in the activity log (Settings, Activity log) with the name of the token as who did it.

Make a token

1. Sign in to LeaveCalc as an owner. Only owners can make tokens.
2. Open Settings, Integrations. In the card API tokens, choose Create token.
3. Under What is it for? type a name that says who uses it, for example “Claude, Dana’s laptop”. The name is what the activity log shows.
4. Under What may it do? choose Only read to start. Choose Read and change only if you want the assistant to ask for time off or to approve and deny requests, and only for a connector that is yours alone.
5. Leave the switch Include the type of sick and medical leave off unless you need it.
6. Choose Create token and copy the token now. LeaveCalc keeps only a fingerprint of it.

Treat the token like a password. Anyone who has it can do what it can do, as the owner who made it, until you remove it. Remove a token in the same list at any time and it stops working at once. A token also stops working when the owner who made it is removed or is no longer an owner. You can have up to 10 tokens.

Connect your assistant

This is the part where products differ most. What we found on 7 October 2026:

Try it by hand

A request with curl, using the 2025-06-18 handshake that most assistants send first. Put the token in a variable first, as in the Claude Code section.

curl -s https://leavecalc.com/api/v1/mcp \
  -H "Authorization: Bearer $LEAVECALC_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

Then list the tools with {"jsonrpc":"2.0","id":2,"method":"tools/list"} and add the header MCP-Protocol-Version: 2025-06-18.

The newer, stateless way (protocol 2026-07-28) has no handshake. Every request carries the version and the matching headers:

curl -s https://leavecalc.com/api/v1/mcp \
  -H "Authorization: Bearer $LEAVECALC_TOKEN" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/call" -H "Mcp-Name: who_is_out" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"who_is_out","arguments":{"date":"2026-11-10"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

The official MCP Inspector (npx @modelcontextprotocol/inspector) can also connect: choose the Streamable HTTP transport, enter the address and add the Authorization header.

Safety advice

• Prefer a read token. A shared (organization-wide) connector must use a read token. Make a second, personal token that can change things only for the people and the moments that need it.
• Keep the token out of your shell history and out of shared files. Give it to the tool through an environment variable.
• An assistant can be fooled by text it reads. A request note or a person’s name is written by an employee, and a hostile one could try to give the assistant orders. LeaveCalc labels such text as untrusted, tells the assistant to treat it as data, and refuses an approval or denial unless the employee and start date match the request. The real protection is yours: keep the assistant’s confirmation prompt on for write tools, and do not choose “always allow” for approve_request or deny_request.
• What the assistant reads goes to the company that runs the assistant (names, dates, balances), under your agreement with them. Do not connect an assistant you would not share your team calendar with. Nothing is sent to LeaveCalc except what the assistant asks for.

If something does not work

What is not there yet

• OAuth. The MCP specification makes authorization optional, but ChatGPT’s connector dialog and most of Claude’s connector paths expect it. To support them LeaveCalc would need to run an authorization server (a sign-in and consent screen where an owner approves the assistant, PKCE, refresh tokens, client registration, token audience binding) and publish protected resource metadata. That is a project of its own and was deliberately not rushed into this release. Until then, only clients that can send a fixed header connect.
• No server-to-assistant streaming. The server answers GET with 405, sends no list-change notifications, and offers tools only (no resources or prompts).
• JSON-RPC batches are accepted only in protocol 2025-03-26, as that revision defines them.
• Directory listings. Claude’s Connectors Directory and the ChatGPT app directory have their own review processes, which also assume OAuth. LeaveCalc is not listed in either.

Protocol details

• One endpoint, POST only. GET, DELETE, PUT and PATCH answer 405 with Allow: POST. There are no sessions: an Mcp-Session-Id header is ignored and never issued.
• Both eras are served on the same address. A request whose params._meta carries io.modelcontextprotocol/protocolVersion is a 2026-07-28 request and must have the headers MCP-Protocol-Version (equal to the body), Mcp-Method (equal to method) and, for tools/call, Mcp-Name (equal to params.name). A mismatch is HTTP 400 with JSON-RPC error -32020, an unknown version is 400 with -32022, a missing _meta field is 400 with -32602, and an unknown method is 404 with -32601. server/discover is implemented.
• Anything else is the older era: initialize (answers the client’s version when it is one of 2025-11-25, 2025-06-18 and 2025-03-26, else 2025-11-25), notifications/initialized (202), ping, tools/list and tools/call.
• Notifications and client responses are answered 202 with no body. Bodies over 256 KB are 413.
• Tool failures the model can fix (bad date, unknown person, refused approval) come back as a normal result with isError: true and a plain sentence. Unknown tools and malformed requests are JSON-RPC errors (-32602). Every tool result has structuredContent and the same JSON as text in content. Lists page with limit (1 to 100) and next_cursor.
• Origin header: present and not on the allowed list is 403 (DNS rebinding protection). Allowed: leavecalc.com, claude.ai, claude.com, chatgpt.com and chat.openai.com. Requests without an Origin header, such as command line tools, are fine.
• Every message of a batch is its own change: a message that fails never undoes an earlier one that succeeded, and the emails and webhooks it causes are sent after its commit.

Specifications used, read 7 October 2026: modelcontextprotocol.io/specification/2026-07-28 and modelcontextprotocol.io/specification/2025-11-25.

Also: API reference · Zapier · Make · SAML single sign-on