Use Impulse with 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.

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.

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

Claude Desktop

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

Download the extension

Download impulse-mcp.mcpb from the latest release.

Install it

Double-click the downloaded file, or open Claude Desktop’s Settings > Extensions, and drag the file onto the page.

Configure (optional)

Open the Impulse extension’s Configure panel to add an API key for authenticated access. Leave it blank to use guest mode.

Enable it

Make sure the extension is turned on in Settings > Extensions, then start a new conversation.

Claude Code

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:

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:

claude mcp list

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

claude -p "Call the impulse_auth_status tool and report the result." --allowedTools "mcp__impulse__impulse_auth_status"

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

.claude/settings.json

{
  "permissions": {
    "allow": [
      "mcp__impulse__*"
    ]
  }
}

First prompt

After connecting, ask Claude to use Impulse:

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:

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:

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:

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:

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.

​Requirements

​Claude Desktop

​Claude Code

​First prompt

​What Claude can do

​Troubleshooting

​impulse_auth_status reports guest mode even though you set an API key

​Claude Code doesn’t show Impulse tools

​The .mcpb file won’t open in Claude Desktop’s install picker

Requirements

Claude Desktop

Claude Code

First prompt

What Claude can do

Troubleshooting

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

Claude Code doesn’t show Impulse tools

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