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 (connector) 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

Add Impulse as a connector (recommended)

The most reliable way to use Impulse in Claude Desktop is as a remote connector — it’s a plain HTTP connection, so there’s no local process for Claude Desktop to manage.

Open Connectors settings

In Claude Desktop, go to Settings > Connectors > Add custom connector.

Enter the server details

Name it Impulse and set the URL to https://api.impulselabs.ai/api/mcp-http.

Connect

Click Connect. Your browser opens to sign in (or sign up) via Impulse — no manual API key needed. Approve access and you’ll be redirected back to Claude, now authenticated.

Enable it for a conversation

Connectors can also be toggled per chat via + > Connectors inside a conversation. Make sure Impulse is on there too, not just in Settings.

Datasets: ask Claude to upload the file with impulse_dataset_upload_base64 (Claude reads the file itself and sends the contents inline). The local-path upload tool described below isn’t available over this connector — a remote server can’t read a path on your machine.

One-click extension (`.mcpb`, optional)

Claude Desktop also supports installing Impulse as a local extension package. This gives Claude direct access to your filesystem (so it can upload a dataset by local path), but the extension runs as a local process that Claude Desktop has to spawn and manage per conversation — in practice this has been less reliable than the connector above, with tools sometimes reporting “disabled” or fully disconnecting mid-conversation. Use this only if you specifically need local-path dataset uploads.

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, and also enabled for the specific conversation via + > Connectors, 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.

The `.mcpb` extension says a tool is “disabled” or disconnects mid-conversation

This is a per-chat toggle issue, not your account or the extension itself: Claude Desktop lets you enable/disable each connector (including installed .mcpb extensions) per conversation via + > Connectors, separate from the global toggle in Settings > Extensions. If that per-chat toggle is off, tool calls get rejected and Claude may describe it as “disabled.” Turn it on for that conversation and retry. If it still shows fully disconnected afterward, the local extension process likely needs a clean restart — start a new conversation rather than continuing the same one. This local-process instability is why the connector is the recommended way to use Impulse in Claude Desktop.

​Requirements

​Claude Desktop

​Add Impulse as a connector (recommended)

​One-click extension (.mcpb, optional)

​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

​The .mcpb extension says a tool is “disabled” or disconnects mid-conversation

Requirements

Claude Desktop

Add Impulse as a connector (recommended)

One-click extension (`.mcpb`, optional)

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

The `.mcpb` extension says a tool is “disabled” or disconnects mid-conversation