Tools - A-Char API

The A-Char MCP server has 9 time-off tools. Each tool runs the same code as its API endpoint, so it takes the same arguments, returns the same data, and follows the same rules.

First call

tools/list returns the tools your credential can use, each with its description, input schema and annotations. Your client calls it when it connects; you can call it yourself:

curl https://a-char.com/api/mcp \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $A_CHAR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

Response (200), abridged to one tool:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "cancel_time_off",
        "title": "Cancel a time-off request",
        "description": "Cancels a pending, approved or declined request and returns its days to the balance...",
        "inputSchema": {
          "type": "object",
          "properties": {
            "id": { "type": "string" },
            "employee_id": { "type": "string" },
            "note": { "type": "string" }
          },
          "required": ["id"]
        },
        "annotations": { "readOnlyHint": false, "destructiveHint": true, "openWorldHint": false }
      }
    ]
  }
}

Time-off tools

Tool	Description
`get_time_off_balances`	Your balance for every active policy
`list_my_time_off`	Your requests and their status
`preview_time_off`	Work out a request without creating it
`request_time_off`	Book time off
`update_time_off`	Change a request
`cancel_time_off`	Cancel a request
`approve_time_off`	Approve a request waiting on you
`decline_time_off`	Decline a request waiting on you
`get_time_off_document`	Download an attachment or generated document

Dates are YYYY-MM-DD. Day types are FULL_DAY, AM (morning) and PM (afternoon), for half days.

get_time_off_balances

Every active policy you are assigned to, with the balance left in the current cycle and the days taken, requested and accrued. Use a policy’s id as policy_id in the tools below.

Parameter	Type	Description	Required	Default
`employee_id`	string	Read someone else’s balances. Needs the admin role or being their approver	No	You

list_my_time_off

Your requests with their status (pending, approved, declined, cancelled), dates, days, policy, each approver’s decision and attachments.

Parameter	Type	Description	Required	Default
`employee_id`	string	Read someone else’s requests. Needs the admin role or being their approver	No	You

preview_time_off

Which days count against the balance once weekends and public holidays are left out, how many that is, and the balance left afterwards. Nothing is created; call it before request_time_off.

Parameter	Type	Description	Required	Default
`policy_id`	string	Policy from `get_time_off_balances`	Yes
`start_date`	string	First day	Yes
`end_date`	string	Last day	Yes
`start_date_type`	string	`FULL_DAY`, `AM` or `PM`	No	`FULL_DAY`
`end_date_type`	string	`FULL_DAY`, `AM` or `PM`	No	`FULL_DAY`
`request_id`	string	When previewing a change to an existing request, so its days are not counted twice	No
`employee_id`	string	Preview for someone else	No	You

request_time_off

Books time off and notifies the approvers, or approves it straight away when the policy needs no approval. Rejected when it would overdraw the balance, overlaps another request, misses the notice period, or falls outside the dates you may book.

Parameter	Type	Description	Required	Default
`policy_id`	string	Policy from `get_time_off_balances`	Yes
`start_date`	string	First day	Yes
`end_date`	string	Last day	Yes
`start_date_type`	string	`FULL_DAY`, `AM` or `PM`	No	`FULL_DAY`
`end_date_type`	string	`FULL_DAY`, `AM` or `PM`	No	`FULL_DAY`
`note`	string	Note for the approvers. Some policies require one	No
`attachments`	file[]	Images and PDFs, 4 MB in total. Some policies require one	No	`[]`
`employee_id`	string	Book for someone else. Needs the admin role or being their approver	No	You

update_time_off

Changes a pending or approved request; a changed request goes back to its approvers. Send only what changes. The policy cannot be changed.

Parameter	Type	Description	Required	Default
`id`	string	The request	Yes
`start_date`	string	New first day	No	Unchanged
`end_date`	string	New last day	No	Unchanged
`start_date_type`	string	`FULL_DAY`, `AM` or `PM`	No	Unchanged
`end_date_type`	string	`FULL_DAY`, `AM` or `PM`	No	Unchanged
`note`	string	New note	No	Unchanged
`attachments`	file[]	Files to add	No	`[]`
`kept_attachment_paths`	string[]	Existing attachments to keep	No	All
`employee_id`	string	Change someone else’s request	No	You

cancel_time_off

Cancels a pending, approved or declined request and returns its days to the balance. Only an admin can cancel leave that has already started. Marked destructive.

Parameter	Type	Description	Required	Default
`id`	string	The request	Yes
`note`	string	Reason for cancelling	No
`employee_id`	string	Cancel someone else’s request	No	You

approve_time_off

Records your approval when it is your turn as approver. Once every approver has approved, the days are deducted and the employee is notified. An admin can approve in place of the approver whose turn it is. Nobody can approve their own request.

Parameter	Type	Description	Required	Default
`id`	string	The request	Yes

decline_time_off

Declines a request waiting on you, returns its days to the balance and notifies the employee. Marked destructive.

Parameter	Type	Description	Required	Default
`id`	string	The request	Yes
`note`	string	Reason, shown to the employee	Yes

get_time_off_document

Returns an attachment, or the generated request, approval or decline document, of a request. Open to the request’s employee, its approvers and admins.

Parameter	Type	Description	Required	Default
`id`	string	Document `id` from the request’s `time_off_documents` in `list_my_time_off`	Yes

How it behaves

Your credential decides the catalog

tools/list only returns tools your credential’s scopes allow, capped by your role. A tool you cannot use is not listed at all, so it never costs the assistant context.

Destructive tools are marked

cancel_time_off and decline_time_off carry destructiveHint: true, and read tools carry readOnlyHint: true. Clients that honour the hints ask before running a destructive tool and may run read tools without asking.

Errors come back as tool results

A rejected call returns isError: true with the reason as text, the same message A-Char shows, for example You already have a time off request for the period 22 December 2026 to 23 December 2026. Please adjust your request. The assistant can explain it or retry with other arguments. An unexpected failure returns Something went wrong. Try again later.

Documents come back as files

get_time_off_document returns images as MCP image content and PDFs as an embedded resource, so clients that render them show the document inline.

`employee_id` acts for someone else

Time-off tools default to you. Passing employee_id acts for that person, and only works when you are an admin or their approver.

MCP: a first tool call over plain HTTP and how the server behaves.
Setup: per-client configuration, API keys, and fixes when it fails.
API reference: the endpoint behind every tool.

​First call

​Time-off tools

​get_time_off_balances

​list_my_time_off

​preview_time_off

​request_time_off

​update_time_off

​cancel_time_off

​approve_time_off

​decline_time_off

​get_time_off_document

​How it behaves

​Your credential decides the catalog

​Destructive tools are marked

​Errors come back as tool results

​Documents come back as files

​employee_id acts for someone else

​Related