Self-Hosted

Run the Check MCP Server locally for full control over your configuration, access control, and environment.

The Check MCP Server is open source software, licensed under the MIT License, and hosted on GitHub in Check's MCP Server & CLI Repository. You can find source code and detailed MCP documentation in README.md.

🚧
The Check MCP Server is currently in beta. While we've tested it extensively, you may encounter unexpected behavior, breaking changes, or limitations.

No stability guarantees — APIs, tool schemas, and behavior may change without notice between releases.

Not recommended for production-critical workflows — Use at your own discretion and validate outputs before acting on them.

Feedback is welcome — Please report bugs, suggest improvements, or share your experience with your Check point of contact.

Prerequisites

Check API key
MCP-compatible client — Claude Desktop, Claude Code, Cursor, GitHub Copilot, ChatGPT, Gemini, Codex, or any MCP client
Python 3.10+ — python.org/downloads
uv — Python package manager (docs.astral.sh/uv)
Git — git-scm.com

Quick start

1. Clone and install

git clone https://github.com/check-technologies/mcp-server-check.git
cd mcp-server-check
uv sync

2. Test the server

export CHECK_API_KEY=your-api-key-here
uv run mcp-server-check

If the server starts without errors, you're ready to connect a client.

3. Connect to an AI client

Choose your client below and follow the configuration instructions.

4. Try it out

Once connected, try these example prompts to verify the setup:

"Generate a CSV of all employees at company X with their federal W-4 filing status, dependents amount, and additional withholding"
"What payrolls for company X are pending approval?"
"Give me a summary of the most recent payroll run for company X"
"Help me update tax settings for company X"

Access control

You can restrict what the MCP server can do using environment variables.

Read-only mode

Disable all write operations (create, update, delete, approve, etc.):

export CHECK_READ_ONLY=true

Limit to specific toolsets

Only expose certain categories of tools:

export CHECK_TOOLSETS=companies,employees

Available toolsets: bank_accounts, companies, compensation, components, contractor_payments, contractors, documents, employees, external_payrolls, forms, payments, payroll_items, payrolls, platform, tax, webhooks, workflows, workplaces

Exclude specific tools

Block individual tools by name:

export CHECK_EXCLUDE_TOOLS=create_bank_account,delete_employee

Combining options

All access control options can be combined:

export CHECK_READ_ONLY=true
export CHECK_TOOLSETS=companies,employees,payrolls
export CHECK_EXCLUDE_TOOLS=delete_company

Filtering precedence: exclude_tools > read_only > tools > toolsets.

Switching to production

By default, the MCP server connects to the Check sandbox environment (sandbox.checkhq.com). To point at the production API:

export CHECK_API_BASE_URL=https://api.checkhq.com

⚠️
Use caution in production. Actions taken through the MCP server are real — payrolls will be processed, payments will be sent, and records will be modified. Consider using read-only mode or toolset filtering to limit what the AI can do.

Connect to an AI client

Claude Desktop

Open Settings → Developer → Edit Config and add the following to claude_desktop_config.json:

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

Replace /full/path/to/mcp-server-check with the absolute path where you cloned the repository. Restart Claude Desktop after saving.

Claude Code (CLI)

Run the following command:

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

Then set your API key:

export CHECK_API_KEY=your-api-key-here

Claude Code will automatically detect the MCP server on the next conversation.

Cursor

Open Cursor → Settings → MCP and add the following server configuration:

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

Replace /full/path/to/mcp-server-check with the absolute path where you cloned the repository.

GitHub Copilot (VS Code)

Create or edit .vscode/mcp.json in your workspace:

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

Replace /full/path/to/mcp-server-check with the absolute path where you cloned the repository.

ChatGPT

ChatGPT supports remote MCP servers only. Start the server with HTTP transport:

export CHECK_API_KEY=your-api-key-here
export CHECK_TRANSPORT=streamable-http
uv run mcp-server-check

Then in ChatGPT, go to Settings → Connected apps → Add MCP server and enter the server URL (default: http://localhost:8000/mcp).

Google Gemini

Gemini supports remote MCP servers. Start the server with HTTP transport:

export CHECK_API_KEY=your-api-key-here
export CHECK_TRANSPORT=streamable-http
uv run mcp-server-check

Then configure Gemini to connect to the server URL (default: http://localhost:8000/mcp).

OpenAI Codex CLI

Add the following to ~/.codex/config.json:

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

Replace /full/path/to/mcp-server-check with the absolute path where you cloned the repository.

Other MCP clients

For any MCP-compatible client, the general pattern is:

Command: uv
Arguments: run --directory /full/path/to/mcp-server-check mcp-server-check
Environment variable: CHECK_API_KEY=your-api-key-here
Transport: stdio (default) for local clients, streamable-http or sse for remote clients

Consult your client's documentation for how to configure MCP servers.