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

# Use Impulse with Claude

> Connect Claude Desktop or Claude Code to the Impulse MCP server and train, inspect, deploy, and run models from Claude

Claude can use Impulse through the Model Context Protocol (MCP). Once connected, Claude can upload datasets, start training sessions, inspect artifacts, deploy models, and run predictions through the Impulse tools.

This guide covers both Claude Desktop (one-click extension) and Claude Code (terminal). For direct REST API calls, see the [Quickstart](/quickstart).

## Requirements

* Claude Desktop or the Claude Code CLI.
* An Impulse account. An API key is optional — guest mode works without one, but sign in with a key for authenticated workflows tied to your account.

<Note>
  Impulse connects to the hosted production gateway (`https://api.impulselabs.ai`) by default. You don't need to run anything yourself.
</Note>

## Claude Desktop

Install Impulse as a Claude Desktop extension (`.mcpb`) — no terminal required.

<Steps>
  <Step title="Download the extension">
    Download [impulse-mcp.mcpb](https://github.com/impulse-ai/impulse-mcp-plugin/releases/latest/download/impulse-mcp.mcpb) from the latest release.
  </Step>

  <Step title="Install it">
    Double-click the downloaded file, or open Claude Desktop's **Settings > Extensions**, and drag the file onto the page.
  </Step>

  <Step title="Configure (optional)">
    Open the Impulse extension's **Configure** panel to add an API key for authenticated access. Leave it blank to use guest mode.
  </Step>

  <Step title="Enable it">
    Make sure the extension is turned on in **Settings > Extensions**, then start a new conversation.
  </Step>
</Steps>

## Claude Code

Register Impulse as an MCP server from the terminal.

```bash theme={null}
claude mcp add --transport http impulse https://api.impulselabs.ai/api/mcp-http \
  --header "x-api-key: <your Impulse API key>" \
  --header "x-impulse-client-surface: claude_code"
```

The `x-api-key` header is optional — omit it to use guest mode. `x-impulse-client-surface` is optional too; it doesn't affect auth, it just tags usage so it's attributed to Claude Code rather than lumped in as `unknown` in your `impulse_usage_summary` breakdown.

By default this registers the server at **local** scope (this project only). Add `-s user` to make it available in every project:

```bash theme={null}
claude mcp add -s user --transport http impulse https://api.impulselabs.ai/api/mcp-http \
  --header "x-api-key: <your Impulse API key>" \
  --header "x-impulse-client-surface: claude_code"
```

Verify it's connected:

```bash theme={null}
claude mcp list
```

You should see `impulse` listed as `✔ Connected`. To check whether it picked up your API key:

```bash theme={null}
claude -p "Call the impulse_auth_status tool and report the result." --allowedTools "mcp__impulse__impulse_auth_status"
```

<Note>
  `--allowedTools` is only needed for non-interactive (`-p`) runs like the check above. In a normal interactive `claude` session, Claude will prompt you to approve Impulse tools the first time it calls one, and you can choose "always allow." To skip the prompt permanently, add `"mcp__impulse__*"` to `permissions.allow` in `.claude/settings.json`.
</Note>

```json .claude/settings.json theme={null}
{
  "permissions": {
    "allow": [
      "mcp__impulse__*"
    ]
  }
}
```

## First prompt

After connecting, ask Claude to use Impulse:

```text theme={null}
Use the Impulse MCP server to train a model from my uploaded dataset. Show me the session id, required artifacts, metrics, and prediction file when the run is complete.
```

If you already have dataset IDs:

```text theme={null}
Use Impulse MCP. Train a tabular classification model with dataset_id=<TRAIN_DATASET_ID> and test_dataset_id=<TEST_DATASET_ID>. The target column is Transported. Produce submission.csv and save the canonical model artifacts.
```

## What Claude can do

Once connected, Claude can use Impulse MCP tools to:

* Upload datasets.
* List datasets and projects.
* Start training sessions.
* Poll session status.
* Inspect generated artifacts.
* Package models for inference.
* Deploy trained models.
* Fetch deployment feature contracts.
* Run predictions against deployed models.

## Troubleshooting

### `impulse_auth_status` reports guest mode even though you set an API key

Check what's actually registered:

```bash theme={null}
claude mcp get impulse
```

Confirm the `x-api-key` header shows your raw key with no `Bearer ` prefix — Impulse's API key auth expects the raw key value, not an `Authorization`-style scheme. If it's wrong, remove and re-add:

```bash theme={null}
claude mcp remove impulse -s local
claude mcp add -s local --transport http impulse https://api.impulselabs.ai/api/mcp-http \
  --header "x-api-key: <your Impulse API key>" \
  --header "x-impulse-client-surface: claude_code"
```

### Claude Code doesn't show Impulse tools

Check the server list:

```bash theme={null}
claude mcp list
```

If `impulse` is missing or not connected, re-add it with the command above, then start a new session.

### The `.mcpb` file won't open in Claude Desktop's install picker

Some macOS file pickers filter by registered file type and may not recognize `.mcpb`. Double-click the downloaded file directly, or drag it onto **Settings > Extensions**, instead of using the picker's "choose file" dialog.