---
updatedAt: 2026-09-22T10:08:33.000Z
agentTools:
  projectIndex: https://docs.checkhq.com/llms.txt
---

# Self-Hosted

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

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](https://github.com/check-technologies/mcp-server-check). You can find source code and detailed MCP documentation in `README.md`.

## 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](https://www.python.org/downloads/)
* **uv** — Python package manager ([docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/))
* **Git** — [git-scm.com](https://git-scm.com/)

## Quick start

### 1. Clone and install

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

### 2. Test the server

```shell
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.):

```bash
export CHECK_READ_ONLY=true
```

### Limit to specific toolsets

Only expose certain categories of tools:

```bash
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:

```bash
export CHECK_EXCLUDE_TOOLS=create_bank_account,delete_employee
```

### Combining options

All access control options can be combined:

```bash
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:

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

<Callout icon="⚠️" theme="error">
  **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.
</Callout>

## Connect to an AI client

### Claude Desktop

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

```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:

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

Then set your API key:

```bash
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:

```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.

### GitHub Copilot (VS Code)

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

```json
{
  "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:

```bash
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:

```bash
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`:

```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.