# Set up MarketCheck AI Desk

> For AI agents. A user sent you this link so you connect MarketCheck AI Desk to the client you are running in. Their message may also carry a Desk key on a second line (`Desk key: mck_...`): that is the credential for step 3. Start with step 1: work out which client that is and go straight to its section. Follow the steps in order. Ask the user only where a step says to.

## What this is

MarketCheck AI Desk is a paid vehicle-data service for AI assistants: finished reports (vehicle valuations, total-loss and diminished-value files, dealer lot scans, stocking guides, market snapshots) and raw market-data tools (live and recently sold listings, VIN history, VIN decoding, price predictions, monthly sold-market statistics), built from MarketCheck's US dealer-listing data. It is one remote MCP server at `https://ai.marketcheck.com/mcp` (Streamable HTTP). CLI and IDE agents authenticate with a Desk key, a static token sent as `Authorization: Bearer <key>`; runs are charged to the team balance the key belongs to. OAuth 2.1 is supported too, for clients that implement MCP authorization (the Claude.ai, ChatGPT and Claude Desktop connectors), and those need no key. Every price in the data is an advertised (listed) price, never a transacted sale price.

## Step 1: work out which client you are running in, then go to its section

- **Claude.ai** (claude.ai in a browser, or the Claude mobile app) or **ChatGPT** (chatgpt.com or its apps): you cannot run commands or edit your own configuration. Go to "Claude.ai and ChatGPT: add the connector" just below; steps 2 to 5 do not apply to you.
- **Claude Desktop**: a connector added on Claude.ai also shows up in Claude Desktop, so the Claude.ai steps below are the quickest route and need no key. If you can edit files on the user's machine, the Claude Desktop entry in step 3 works as well.
- **Claude Code, Codex, Cursor, VS Code, Gemini CLI, opencode, Windsurf**, or any other MCP client that can run commands and write files: continue with step 2.
- Not sure? Claude Code sets `CLAUDECODE=1` in the shells it spawns. Otherwise look for the configuration files named in step 3, or ask the user which client this is.

## Claude.ai and ChatGPT: add the connector

Connectors are added by the user in the app's own settings, so you cannot add this one yourself. Give the user the steps for their app, with these exact links, then wait until they say it is connected. No key is involved: the connector signs in with OAuth, so a Desk key in the user's message is not used here (do not repeat it back). The same buttons are on https://ai.marketcheck.com/getting-started.

### Claude.ai

1. Open https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=MarketCheck+AI+Desk&connectorUrl=https%3A%2F%2Fai.marketcheck.com%2Fmcp
   It opens Claude's "Add custom connector" dialog with the name and URL filled in. If the fields are empty: Settings, Connectors, Add custom connector, then Name `MarketCheck AI Desk` and Remote MCP server URL `https://ai.marketcheck.com/mcp`.
2. Click **Add**. Claude's red "suggested by an external link" banner is normal; check that the dialog names MarketCheck AI Desk.
3. Click **Connect** on the new connector, sign in with your email and approve access.
4. Start a new chat. The tools are there, and in Claude Desktop too.

Works on Claude Pro, Max, Team and Enterprise. "Missing permissions" means a Team or Enterprise workspace lets only admins add connectors: the user asks their admin to allow members or to add it once for everyone, or uses a personal Claude Pro or Max account with the same email (same AI Desk balance).

### ChatGPT

1. Works on every ChatGPT plan, including Free. Developer Mode is not needed.
2. Open https://chatgpt.com/plugins#settings/Connectors?create-connector=true&redirectAfter=%2Fplugins
   It opens the **Add custom MCP server** dialog (in ChatGPT: Plugins, Add, Add custom MCP server). Name `MarketCheck AI Desk`, Connection `https://ai.marketcheck.com/mcp`, Authentication **OAuth**.
3. Tick "I understand and want to continue" under the "Custom MCP servers introduce risk" notice (expected), then click **Create as a plugin**.
4. Click **Connect**, sign in on the MarketCheck AI Desk consent page and click **Allow**. The tools appear in the chat.

### Once the user says it is connected

- Call `get_account_status`: it returns the account and the team balance, which proves the connection.
- Paid reports need a balance on the team. If it is low, offer: "Ask me to add credits." The `add_credits` tool charges the saved card, or returns a secure checkout link when no card is saved. Credits appear once Stripe confirms the payment.
- Each tool description states its price: confirm it with the user before every paid run.
- Stop here. Steps 2 to 5 are for agents that write their own configuration.

## Step 2: get a Desk key

If the user already gave you a key (the `Desk key:` line of their message, or pasted; it starts with `mck_live_` or `mck_test_`), use it and go to step 3.

Otherwise get one with the device flow. No account is needed up front: the user signs in, or creates an account, when they approve.

1. Start the request. `client_name` is what the user sees on the approval page and becomes the key's name, so use your client's name.

```bash
curl -s -X POST https://ai.marketcheck.com/api/keys/device \
  -H "Content-Type: application/json" \
  -d '{"client_name":"Claude Code"}'
```

The response:

```json
{
  "device_code": "(40 hex characters)",
  "user_code": "WXYZ-1234",
  "verification_uri": "https://ai.marketcheck.com/activate",
  "verification_uri_complete": "https://ai.marketcheck.com/activate?code=WXYZ-1234",
  "expires_in": 900,
  "interval": 5
}
```

2. Tell the user, in these words or close to them: "Open `verification_uri_complete` and approve the request. The code is `user_code`. Sign in with your email if asked." Use the real values. Only a team owner or billing manager can approve; a brand-new account owns its own team. Keep `device_code` to yourself: it is the credential.

3. Poll every `interval` seconds until a key comes back:

```bash
curl -s -X POST https://ai.marketcheck.com/api/keys/device/token \
  -H "Content-Type: application/json" \
  -d '{"device_code":"<device_code>"}'
```

| Response | What to do |
|---|---|
| `{"error":"authorization_pending"}` | Not approved yet. Wait `interval` seconds and poll again. |
| `{"error":"slow_down"}` | Add 5 seconds to your interval, then keep polling. |
| `{"error":"expired_token"}` | The code expired (after 15 minutes). Start again at 1 and give the user the new code. |
| `{"error":"access_denied"}` | The user declined. Stop and tell them. |
| Any other error | Start again at 1. |
| `{"api_key":"mck_...","key_id":"...","key_name":"...","team_name":"...","mcp_url":"...","header":"..."}` | Done. The key is returned once: use `api_key` in step 3. |

Treat the key like a password. Do not repeat it back in full, and never write it into a file that is committed to version control.

## Step 3: write the configuration

Use the section for your client and replace `<YOUR_DESK_KEY>` with the key. When the file already exists, merge the `marketcheck` entry into it and keep everything else; never overwrite the file. Prefer the user-level (every project) location.

### Claude Code

<!-- Snippet verified against https://code.claude.com/docs/en/mcp on Sep 29, 2026. -->

Run in a terminal:

```bash
claude mcp add --transport http --scope user marketcheck https://ai.marketcheck.com/mcp --header "Authorization: Bearer <YOUR_DESK_KEY>"
```

- `--scope user` makes it available in every project. Leave it out to add it to the current project only.
- Check it with `claude mcp list`, or `/mcp` inside a session.
- Start a new Claude Code session so the server loads.

### Codex

<!-- Snippet verified against https://developers.openai.com/codex/mcp on Sep 29, 2026. -->

Where it goes: ~/.codex/config.toml

```toml
[mcp_servers.marketcheck]
url = "https://ai.marketcheck.com/mcp"
http_headers = { Authorization = "Bearer <YOUR_DESK_KEY>" }
```

- Replace an existing `[mcp_servers.marketcheck]` table rather than adding a second one.
- To keep the key out of the file, use `bearer_token_env_var = "MARKETCHECK_DESK_KEY"` in place of `http_headers` and export that variable.
- Restart Codex.

### Cursor

<!-- Snippet verified against https://cursor.com/docs/context/mcp on Sep 29, 2026. -->

Where it goes: ~/.cursor/mcp.json (every project) or .cursor/mcp.json (this project)

```json
{
  "mcpServers": {
    "marketcheck": {
      "url": "https://ai.marketcheck.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_DESK_KEY>"
      }
    }
  }
}
```

- If the file exists, add the `marketcheck` entry inside `mcpServers` and keep the others.
- A project `.cursor/mcp.json` that holds a key belongs outside version control.
- Restart Cursor, or refresh the server in its MCP settings.

### VS Code

<!-- Snippet verified against https://code.visualstudio.com/docs/copilot/customization/mcp-servers and https://code.visualstudio.com/docs/copilot/reference/mcp-configuration on Sep 29, 2026. -->

Where it goes: .vscode/mcp.json (this workspace), or your user mcp.json (command: MCP: Open User Configuration)

```json
{
  "servers": {
    "marketcheck": {
      "type": "http",
      "url": "https://ai.marketcheck.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_DESK_KEY>"
      }
    }
  }
}
```

- Prefer the user mcp.json for a personal key: `.vscode/mcp.json` is usually committed with the workspace.
- VS Code can prompt for the key instead: set the header to `Bearer ${input:marketcheck-key}` and add a `promptString` input with `"password": true`.
- Run MCP: List Servers and start marketcheck, or reload the window.

### Gemini CLI

<!-- Snippet verified against https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md on Sep 29, 2026. -->

Where it goes: ~/.gemini/settings.json (every project) or .gemini/settings.json (this project)

```json
{
  "mcpServers": {
    "marketcheck": {
      "httpUrl": "https://ai.marketcheck.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_DESK_KEY>"
      }
    }
  }
}
```

- Use `httpUrl`: plain `url` means the older SSE transport.
- Merge into the existing settings.json; it holds your other Gemini CLI settings.
- Or run `gemini mcp add --transport http --header "Authorization: Bearer <YOUR_DESK_KEY>" marketcheck https://ai.marketcheck.com/mcp`.
- Restart Gemini CLI, then run /mcp to see the server.

### opencode

<!-- Snippet verified against https://opencode.ai/docs/mcp-servers/ on Sep 29, 2026. -->

Where it goes: ~/.config/opencode/opencode.json (every project) or opencode.json (this project)

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "marketcheck": {
      "type": "remote",
      "url": "https://ai.marketcheck.com/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer <YOUR_DESK_KEY>"
      }
    }
  }
}
```

- If the file exists, add the `marketcheck` entry inside `mcp` and keep the rest.
- Restart opencode.

### Windsurf

<!-- Snippet verified against https://docs.windsurf.com/windsurf/cascade/mcp on Sep 29, 2026. -->

Where it goes: ~/.codeium/windsurf/mcp_config.json (Devin Desktop, its successor: ~/.config/devin/mcp_config.json)

```json
{
  "mcpServers": {
    "marketcheck": {
      "serverUrl": "https://ai.marketcheck.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_DESK_KEY>"
      }
    }
  }
}
```

- Windsurf calls the URL field `serverUrl`.
- On Windows, Devin Desktop reads `%APPDATA%\devin\mcp_config.json`.
- Restart the editor, or refresh the MCP servers in the Cascade panel.

### Claude Desktop

<!-- Snippet verified against https://github.com/geelen/mcp-remote and https://modelcontextprotocol.io/docs/develop/connect-local-servers on Sep 29, 2026. -->

Where it goes: claude_desktop_config.json (Settings, Developer, Edit Config)

```json
{
  "mcpServers": {
    "marketcheck": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://ai.marketcheck.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <YOUR_DESK_KEY>"
      }
    }
  }
}
```

- No key needed on the connector route: a connector added on Claude.ai also appears in Claude Desktop.
- This file route needs Node.js; `mcp-remote` bridges the remote server into the app.
- The header rides in `AUTH_HEADER` because Claude Desktop on Windows mangles spaces inside `args`.
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`. Windows: `%APPDATA%\Claude\claude_desktop_config.json`.
- Quit Claude Desktop completely and open it again.

### Any other MCP client

- Endpoint: `https://ai.marketcheck.com/mcp` (Streamable HTTP: JSON-RPC over POST).
- Header: `Authorization: Bearer <YOUR_DESK_KEY>`.
- No key at all also works for a client that implements MCP authorization: OAuth 2.1 with dynamic client registration, discovered from `https://ai.marketcheck.com/.well-known/oauth-protected-resource/mcp`. The client walks the user through sign-in and consent.

## Step 4: restart and verify

Restart the client, or start a new session, so it loads the server (each section above says how). Then call the `get_account_status` tool: a working setup returns the team balance.

To test the key itself before restarting:

```bash
curl -s -X POST https://ai.marketcheck.com/mcp \
  -H "Authorization: Bearer <YOUR_DESK_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_account_status","arguments":{}}}'
```

A 401 with a `WWW-Authenticate` header means the key is wrong, rotated or revoked. Get a new one (step 2).

## Step 5: tell the user

- Setup is done: name the client, and the team the key belongs to (`team_name` from step 2, or the account in `get_account_status`).
- Paid reports need a balance on the team. If the balance is low, the user adds credits at https://ai.marketcheck.com/account/billing (a Desk key cannot add credits itself).
- Reports cost from $0.50 per VIN or $0.99 per run, and each tool description states its exact price: confirm the price with the user before every paid run. Raw data tools cost from $0.01 per call.
- The market insights tool (`get_market_insights`) is priced in call units by the shape of the question.
- Keys are managed at https://ai.marketcheck.com/account/keys: rename, set limits, rotate, revoke.

People setting up by hand can use https://ai.marketcheck.com/getting-started. More on server-side use of AI Desk: https://ai.marketcheck.com/ai/docs/server-side-access/
