> ## Documentation Index
> Fetch the complete documentation index at: https://penseapp.vercel.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Configure the Calibrate MCP server in your coding agent

Connect the Calibrate MCP server to your coding agent one of two ways: the
**hosted** endpoint (recommended — nothing to install), or a **local** server run
with `npx`. Both need a Calibrate API key — create one under
[**Workspace settings → API keys**](https://calibrate.artpark.ai/workspace-settings?tab=api-keys).

## Config file locations

Where each client stores its MCP config:

<Tabs>
  <Tab title="macOS">
    * **Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Cursor** — `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project)
    * **Claude Code** — `~/.claude.json` (or `.mcp.json` in a project)
  </Tab>

  <Tab title="Windows">
    * **Claude Desktop** — `%APPDATA%\Claude\claude_desktop_config.json`
    * **Cursor** — `%USERPROFILE%\.cursor\mcp.json` (or `.cursor\mcp.json` in a project)
    * **Claude Code** — `%USERPROFILE%\.claude.json` (or `.mcp.json` in a project)
  </Tab>

  <Tab title="Linux">
    * **Claude Desktop** — `~/.config/Claude/claude_desktop_config.json`
    * **Cursor** — `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project)
    * **Claude Code** — `~/.claude.json` (or `.mcp.json` in a project)
  </Tab>
</Tabs>

## Hosted server (recommended)

Point your client at the managed endpoint
`https://mcp.calibrate.artpark.ai/mcp` via
[`mcp-remote`](https://www.npmjs.com/package/mcp-remote), passing your API key in
the `X-API-Key` header. Nothing to install or keep updated.

<Tabs>
  <Tab title="Claude Desktop">
    Add to `claude_desktop_config.json` (see paths above):

    ```json theme={null}
    {
      "mcpServers": {
        "calibrate": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://mcp.calibrate.artpark.ai/mcp",
            "--header",
            "X-API-Key: ${CALIBRATE_API_KEY}"
          ],
          "env": {
            "CALIBRATE_API_KEY": "your_api_key"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "calibrate": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://mcp.calibrate.artpark.ai/mcp",
            "--header",
            "X-API-Key: ${CALIBRATE_API_KEY}"
          ],
          "env": {
            "CALIBRATE_API_KEY": "your_api_key"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http calibrate \
      https://mcp.calibrate.artpark.ai/mcp \
      --header "X-API-Key: your_api_key"
    ```
  </Tab>
</Tabs>

<Warning>
  Fully quit and reopen your client after editing its config — Claude Desktop
  needs a complete restart, not just a new window.
</Warning>

## Local server (npx)

Run the server on your own machine from the
[`@dalmia/calibrate-mcp`](https://www.npmjs.com/package/@dalmia/calibrate-mcp)
package. It talks directly to the Calibrate API — no `mcp-remote` in between.

<Tabs>
  <Tab title="Claude Desktop">
    Add to `claude_desktop_config.json` (see paths above):

    ```json theme={null}
    {
      "mcpServers": {
        "calibrate": {
          "command": "npx",
          "args": ["-y", "@dalmia/calibrate-mcp", "start"],
          "env": {
            "CALIBRATE_API_KEY_AUTH": "your_api_key"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    ```json theme={null}
    {
      "mcpServers": {
        "calibrate": {
          "command": "npx",
          "args": ["-y", "@dalmia/calibrate-mcp", "start"],
          "env": {
            "CALIBRATE_API_KEY_AUTH": "your_api_key"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add calibrate -- npx -y @dalmia/calibrate-mcp start --api-key-auth your_api_key
    ```
  </Tab>
</Tabs>

## Environment variables

| Variable                 | Required | Default | Description                                                                                    |
| ------------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------- |
| `CALIBRATE_API_KEY_AUTH` | Yes      | —       | Your API key for the **local** server. Equivalent to the `--api-key-auth` flag.                |
| `CALIBRATE_API_KEY`      | Yes      | —       | Your API key for the **hosted** server, injected into the `X-API-Key` header for `mcp-remote`. |
| `CALIBRATE_DEBUG`        | No       | `false` | Set to `true` for verbose logging (local server).                                              |

For self-hosted Calibrate deployments, run the local server with `--server-url`
pointing at your API instance:

```bash theme={null}
npx -y @dalmia/calibrate-mcp start \
  --api-key-auth "$CALIBRATE_API_KEY_AUTH" \
  --server-url https://calibrate.my-company.internal
```

## Local development

To run from a local clone:

```bash theme={null}
git clone https://github.com/dalmia/calibrate-mcp
cd calibrate-mcp
npm install
npm run build
node bin/mcp-server.js start --api-key-auth your_api_key
```

### MCP Inspector

Inspect the tools interactively with the
[MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) — a web UI
for testing tool calls:

```bash theme={null}
npx @modelcontextprotocol/inspector node bin/mcp-server.js start
```