薪资管理MCP服务器

mcp-server-check

⚠️ Early Access Beta — This MCP server is currently in beta and available to select partners. APIs, tools, and behavior may change without notice. Please share feedback with your Check point of contact.

Terms of Service — By using this MCP server to access the Check API, you agree to the MCP Usage Terms, which are in addition to your existing agreement with Check.

An MCP server that wraps the Check Payroll API, providing 268 tools for managing companies, employees, contractors, payrolls, tax configuration, embedded components, and more.

Quickstart

git clone https://github.com/check-technologies/mcp-server-check.git
cd mcp-server-check
uv sync
CHECK_API_KEY=your-key uv run mcp-server-check

Configuration

Sandbox vs Production

By default the server connects to the Check sandbox (https://sandbox.checkhq.com), which is safe for testing and development. The sandbox supports simulation endpoints (e.g. simulate_start_processing, simulate_complete_funding) that let you advance payrolls through processing states without real money movement.

To point at production, set:

CHECK_API_BASE_URL=https://api.checkhq.com

Server Configuration

The server supports fine-grained tool filtering, configurable via environment variables (for stdio) or HTTP headers (for SSE / streamable-http). This follows the GitHub MCP Server configuration pattern.

Filtering precedence: exclude_tools > category exclusions (money movement, destructive) > preview_toolsets > read_only > tools > toolsets. Exclude always wins; category exclusions apply even to tools named in the tools allowlist; a preview toolset stays hidden until it is opted into, even if tools or toolsets names it; if tools is set it acts as an allowlist independent of toolsets.

Toolsets

There are 21 toolsets, one per API module: agencies, bank_accounts, companies, compensation, components, contractor_payments, contractors, documents, employees, external_payrolls, forms, logs, payments, payroll_items, payrolls, platform, report_runs, tax, webhooks, workflows, workplaces.

Enable only specific toolsets:

CHECK_TOOLSETS=companies,employees CHECK_API_KEY=your-key uv run mcp-server-check

Individual Tools

Allow only specific tools by name:

CHECK_TOOLS=list_companies,get_company,list_employees CHECK_API_KEY=your-key uv run mcp-server-check

Excluding Tools

Hide specific tools while keeping everything else:

CHECK_EXCLUDE_TOOLS=create_company,delete_company CHECK_API_KEY=your-key uv run mcp-server-check

Read-Only Mode

Set CHECK_READ_ONLY=1 to run the server with only read-only tools (list, get, download, preview, etc.). All create, update, delete, and other mutating tools are excluded. This is useful when you want to allow exploration of your Check data without risk of modifications.

CHECK_READ_ONLY=1 CHECK_API_KEY=your-key uv run mcp-server-check

Preview Toolsets

Toolsets for APIs still being piloted with specific partners are hidden unless the client opts in. Opt in with any of:

# Local (stdio)
CHECK_PREVIEW_TOOLSETS=<toolset> CHECK_API_KEY=your-key uv run mcp-server-check

# Remote: HTTP header
X-MCP-Preview-Toolsets: <toolset>

# Remote: query parameter, for clients that can only be configured with a URL
https://<server>/mcp?preview_toolsets=<toolset>

Opting in works the same in sandbox and production, and either the server or the client can do it. Once enabled, the toolset behaves like any other: read-only mode, exclude_tools, toolsets, and category exclusions still apply. Opting in only makes the tools visible — the Check API still decides per partner whether the underlying endpoints are available, so a partner without access gets "not found" or "feature unavailable" errors.

Category Exclusions

Two flags remove whole categories of tools from a deployment. Unlike CHECK_EXCLUDE_TOOLS, they do not need updating as tools are added.

CHECK_EXCLUDE_MONEY_MOVEMENT=1 removes the tools that move funds or change where funds are drawn from and sent to: approve_payroll, retry_payment, refund_payment, cancel_payment, and create/update/delete_bank_account.

CHECK_EXCLUDE_DESTRUCTIVE=1 removes tools with irreversible effects — everything matching delete_, bulk_delete_, approve_, cancel_, refund_, simulate_, plus start_implementation, cancel_implementation, sync_accounting, and reopen_correction.

CHECK_EXCLUDE_MONEY_MOVEMENT=1 CHECK_EXCLUDE_DESTRUCTIVE=1 CHECK_API_KEY=your-key uv run mcp-server-check

With both set, an agent can still prepare a payroll run (create_payroll, create_payroll_item, create_contractor_payment, preview_payroll) but cannot approve or disburse it, and cannot add or repoint a bank account. Excluded tools are hidden from list_tools and search_tools, and calling one directly returns an error before any API request is made.

HTTP Headers (Remote Transport)

When running with CHECK_TRANSPORT=sse or CHECK_TRANSPORT=streamable-http, clients can pass configuration via HTTP headers:

X-MCP-Toolsets: companies,employees
X-MCP-Readonly: true
X-MCP-Exclude-Tools: create_company,delete_company
X-MCP-Exclude-Money-Movement: true
X-MCP-Exclude-Destructive: true

Header and environment settings are merged, taking the most restrictive value for each. A client can narrow what the server exposes but never widen it: if the server sets CHECK_READ_ONLY=1 or a category exclusion, no header can turn it off. Preview toolsets and code mode are the exceptions: either side can opt in.

Dynamic Tool Mode (Default)

By default, the server runs in dynamic mode (CHECK_TOOL_MODE=dynamic), exposing 3 meta-tools instead of all individual tools. This avoids sending every tool schema to the LLM upfront, saving significant context window space.

• search_tools(query, toolset?, limit?) — Search for tools by keyword with synonym matching. Returns matching tools with their full parameter schemas.
• list_toolsets() — List all available toolsets with descriptions and example tools.
• run_tool(tool_name, arguments?) — Execute a tool by name with a dict of arguments.

The LLM workflow becomes: browse toolsets or search for relevant tools → review their parameter schemas → call run_tool with the correct arguments. All filtering (CHECK_TOOLSETS, CHECK_READ_ONLY, etc.) is applied at both the search and execution layers.

Set CHECK_TOOL_MODE=all to expose all tools individually (legacy mode):

CHECK_TOOL_MODE=all CHECK_API_KEY=your-key uv run mcp-server-check

Code Mode (experimental)

Code mode follows the pattern described by Cloudflare and Rippling: instead of one tool call per API request, the model writes a short Python program that calls many tools and returns only the answer. Intermediate results never pass through the model's context.

It needs the code extra, which installs Pydantic Monty, a sandboxed Python interpreter:

uv sync --extra code
CHECK_CODE_MODE=1 CHECK_API_KEY=your-key uv run mcp-server-check

A dynamic-mode server can also switch it on per request, which lets a remote deployment roll it out client by client:

# Remote: header
X-MCP-Code-Mode: 1

# Remote: query parameter, for clients that can only be configured with a URL
https://<server>/mcp?code_mode=1

Without the header, a dynamic-mode server lists only the three meta-tools and refuses calls to run_code and get_stubs. With it, only get_stubs and run_code are listed and the three meta-tools are refused, so every API call goes through a program. To refuse the opt-in, set CHECK_EXCLUDE_TOOLS=run_code,get_stubs on the server. The code-mode server instructions are only sent when the server itself sets CHECK_CODE_MODE; a client enabling it by header relies on the tool descriptions. Code mode is part of dynamic mode, so it has no effect under CHECK_TOOL_MODE=all.

Code mode replaces the three dynamic-mode tools with two, so every API call goes through a program:

• get_stubs(query?, toolset?, tools?) — With no arguments, the catalog: every toolset with its description and tool names, write tools marked with *. With a keyword query, a toolset, or a list of tools, typed Python signatures (with docstrings) for the check module, one async def per tool.
• run_code(code, writes?) — Run a program. The check module is pre-imported and exposes every allowed tool as an async function; the program's last expression is returned along with anything it printed and a trace of every tool call it made (tool, arguments, status, duration). The program is type-checked against the stubs before it runs, so a wrong name or argument fails without touching the API.

import asyncio

page = await check.list_employees(company="com_xxx", limit=100)
snapshots = await asyncio.gather(
    *[check.get_employee(employee_id=e["id"]) for e in page["results"]]
)
[e["id"] for e in snapshots if not e.get("bank_accounts")]

How it works:

1. Stubs come from the tool functions. code_mode.render_stubs introspects the same functions run_tool runs (signature, defaults, docstring) and renders a .pyi-style stub file for the check module. There is no second catalog to keep in sync; a new tool gets a stub automatically.
2. Each program gets a fresh sandbox. run_code starts a Monty worker process (about 10ms), registers one host function per allowed tool as the check module, imports it, and feeds the program in. Monty type-checks the program against the stubs first, so a wrong tool name or argument surfaces as type_check_failed before any API call. A doubt about an argument's type (the checker infers types from untyped JSON, so a variable assigned in a loop looks like str | None to it) does not block the run; it comes back in a warnings list beside the result.
3. Calls proxy back to the host. When the program awaits check.list_employees(...), the sandbox suspends and the host runs the tool through ToolIndex.run, so validation, the ToolFilter, and error conversion apply as they do for run_tool. MCP middleware runs once, around run_code itself, so failed reports inside a program don't get recovery alternatives or hints, and the server logs a failed program's call trace without its arguments, output, or source. Only the tool's result crosses back into the sandbox; the API key never does.
4. The result is the program's last expression plus captured print output and a call trace (tool, arguments, status, duration). A failed API call raises RuntimeError inside the sandbox with the usual JSON error payload, so a program can catch it and continue; an uncaught error returns the trace so far.
5. Every call is visible. The trace comes back as its own content block, one line per call, and the server instructions tell the model to repeat it when reporting the result. While the program runs, each finished call is also sent as an MCP progress notification (list_employees(company='com_x') ok 340ms), which clients that request progress, such as Claude Code, show on the running tool. MCP has no per-call approval inside a program; that is what the writes declaration is for.

Guardrails:

• The sandbox has no network, filesystem, or environment access and never sees the API key; every check.* call proxies to the same tool function run_tool would run, through the same ToolFilter, so CHECK_READ_ONLY, toolsets, and category exclusions apply unchanged.
• Write tools are absent from check unless the program names them in run_code's writes argument, which keeps every write visible in the client's tool-call stream before it runs. A declared write that the filter hides is an error.
• The sandbox is a Python subset with a fixed set of standard-library modules (asyncio, base64, bisect, collections, copy, csv, dataclasses, datetime, functools, hashlib, itertools, json, math, random, re, time, typing, unicodedata) and no third-party packages; json.dumps takes indent and sort_keys but not default; asyncio has only gather and sleep (the server caps concurrency and retries throttled calls, so programs need no semaphore); there is no async with, async for, yield, class inheritance, or del; and generator expressions evaluate eagerly to lists. The program's last expression is the answer, serialized by the server, so programs rarely need json at all. An import the sandbox cannot resolve fails type-checking before anything runs, and a failure caused by one of these limits carries a hint the model can act on.
• Each program gets its own sandbox process with a time budget, a call budget, a concurrency cap on API calls, and a heap limit, and the server runs at most CHECK_CODE_MAX_PROGRAMS of them at once (see the CHECK_CODE_* variables in the configuration table). When a program ends with calls still in flight (a timeout, or one call of a gather failing), the host cancels them and they show "status": "pending" in the trace; a pending write may already have landed. Throttled calls (HTTP 429) are retried by the host with the wait the API asks for, and one throttled call pauses every call of the program for that long, so a gather of a hundred calls drains at the rate the API allows instead of each call discovering the limit on its own. A read whose connection dropped is retried the same way; a write is not, since it may have landed. The trace records the retries.

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "check": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-server-check", "mcp-server-check"],
      "env": {
        "CHECK_API_KEY": "your-api-key"
      }
    }
  }
}

Usage with Claude Code

claude mcp add check -- uv run --directory /path/to/mcp-server-check mcp-server-check

Then set the CHECK_API_KEY environment variable in your shell before running Claude Code.

Available Tools

268 tools organized across 17 categories. All list tools support limit and cursor parameters for cursor-based pagination — pass the cursor value from a previous response to fetch the next page.

Companies (26 tools)

Employees (17 tools)

Contractors (10 tools)

Workplaces (4 tools)

Payrolls (15 tools)

Payroll Items (8 tools)

Contractor Payments (6 tools)

External Payrolls (8 tools)

Compensation (32 tools)

Pay schedules, benefits, post-tax deductions, company benefits, earning rates, earning codes, and net pay splits.

Bank Accounts (6 tools)

Documents (19 tools)

Report Runs (4 tools)

Asynchronous reporting. create_report_run returns a run_ ID, get_report_run polls it until the status is completed or failed, and download_report_run returns a link to a ZIP of CSVs. Unlike get_company_report, a run is not scoped to one company unless you pass company.

Forms (4 tools)

Logs (2 tools)

Payments (6 tools)

Tax (26 tools)

Tax parameters, elections (including tax exemptions), filings, statements, packages, and tax reference data.

Agencies (2 tools)

The counterparties Check files and remits to (IRS, state revenue departments). Global read-only reference data.

Webhooks (7 tools)

Platform (28 tools)

Notifications, communications, usage, integrations, accounting, company groups, addresses, setups, and requirements.

Embedded Components (35 tools)

Generate embeddable UI component URLs via POST /{entity_type}/{entity_id}/components/{component_type}. All tools accept an entity_id and optional data configuration.

Company components (25): create_company_previous_provider_access_component, create_company_accounting_integration_component, create_company_authorization_documents_component, create_company_business_details_component, create_company_checklist_component, create_company_company_reports_component, create_company_connect_bank_account_component, create_company_details_component, create_company_early_enrollment_component, create_company_employee_setup_component, create_company_filing_authorization_component, create_company_filing_preview_component, create_company_full_service_setup_submission_component, create_company_integrations_component, create_company_integrations_authorize_component, create_company_pay_history_component, create_company_payment_setup_component, create_company_progress_tracker_component, create_company_run_payroll_component, create_company_signatory_agreements_component, create_company_tax_documents_component, create_company_tax_setup_component, create_company_team_setup_component, create_company_terms_of_service_component, create_company_verification_documents_component

Employee components (9): create_employee_benefits_component, create_employee_payment_setup_component, create_employee_paystubs_component, create_employee_post_tax_deductions_component, create_employee_profile_component, create_employee_ssn_setup_component, create_employee_tax_documents_component, create_employee_tax_setup_component, create_employee_withholdings_setup_component

Contractor components (1): create_contractor_tax_documents_component

Development

git clone https://github.com/check-technologies/mcp-server-check.git
cd mcp-server-check
uv sync --group dev
uv run pytest  # 311 tests

Pre-commit hooks

This repo ships a pre-commit config that runs ruff check and ruff format (the same checks as CI) before each commit. Enable it once after cloning:

uv run pre-commit install

To run the hooks manually against all files: uv run pre-commit run --all-files.