Claude + spectro-kernel end-to-end¶

This walks through using Claude Desktop (or any MCP-aware agent) to analyse a spectrum from start to finish, without writing a single line of Python in the conversation. The agent drives the catalogue through the spectro-mcp server, you just describe what you want.

It is the agent-driven analysis use case the landing page advertises, in practice.

1. Make the MCP server reachable¶

Two terminals, two minutes.

Terminal A - run the kernel locally:

pip install "spectro-kernel[mcp,catalogs,viz]"
spectro-mcp --http --host 127.0.0.1 --port 8000

…or use a deployed one on any container host and skip ahead.

Terminal B - confirm Claude can reach it:

curl -s http://127.0.0.1:8000/health
# → {"status":"ok"}

2. Wire Claude Desktop¶

Open the config file at ~/Library/Application Support/Claude/claude_desktop_config.json (%APPDATA%\Claude\claude_desktop_config.json on Windows) and add:

{
  "mcpServers": {
    "spectro-kernel": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

For a deployed server with an API key, add a headers block:

{
  "mcpServers": {
    "spectro-kernel": {
      "url": "https://spectro-mcp-abcd.ondigitalocean.app/mcp",
      "headers": { "X-API-Key": "sk-live-…" }
    }
  }
}

Quit and reopen Claude Desktop. A small plug icon at the bottom of the conversation now reads spectro-kernel - 70+ tools (the exact count matches spectro info).

3. A first end-to-end conversation¶

Drop a spectrum on disk that the MCP host can see - say /tmp/deneb.fits, and ask Claude in plain language:

"There's a FITS spectrum at /tmp/deneb.fits. Load it, normalise the continuum, look for Balmer lines, and tell me the H-alpha equivalent width."

Watch the tool calls in the right-hand pane:

Step	Tool Claude picks	What goes across
1	`create_session`	`{}`
2	`load_spectrum`	`{ session_id, path: "/tmp/deneb.fits" }`
3	`normalize_polynomial`	`{ session_id, params: { order: 3 } }`
4	`detect_lines`	`{ session_id, params: { catalog: "balmer" } }`
5	`equivalent_width`	`{ session_id, params: { line_center_angstrom: 6562.79, window_angstrom: 30 } }`
6	`get_session_state`	`{ session_id }` (Claude often reads back the metrics before answering)

Claude's final reply quotes the actual numbers (SNR, list of matched lines, EW in Å, EW sign convention) - with the references printed in each tool's description, so its answer is grounded in the kernel's references field.

4. Things that work surprisingly well¶

"Compare the three SNR estimates on this spectrum and tell me which to trust here." Claude reaches for compare_snr_methods, reads the spread, reports the discrepancy in plain English.
"Fit H-alpha with Gaussian, Lorentzian and Voigt - which profile wins?" → compare_line_fits, then Claude picks the highest R².
"Run the balmer_quick preset, then tell me the FWHM of each line." → run_preset once, then get_session_state to read back the line fits.
"Why did you pick this normalisation?" - Claude pulls describe_algorithm on the algorithms it used and quotes the long_description / references to justify its choices.

5. Things that don't work yet¶

Uploading a FITS through the chat. load_spectrum reads a server-side path. Claude Desktop has no MCP-native file-transfer tool; you have to drop the FITS somewhere the MCP host can see it (/tmp/, a shared volume, a presigned S3 URL the user fetches into the server).
Long-running operations. A multi-minute reduction blocks the session. For batch work, kick off a background job (cron / GH Actions / arq) and ask Claude to inspect the results, not to run them.
Visual outputs. Plotly figures land in ctx.figures as JSON; Claude describes them but cannot render. Pair the MCP server with a thin dashboard (see the multi-star viewer cookbook) if you want the plots back in the conversation.

6. A second example: a comparison conversation¶

"I have spectra at /data/star_blue.fits and /data/star_red.fits. Load both, normalise each with the polynomial method, and tell me the SNR difference between them."

Claude opens two sessions in parallel, runs the same chain in each, and contrasts the metrics. The audit trail in each session is fully recorded, ask "show me the history of session s_xyz" and Claude calls get_session_state and reads back every ProcessingStep.

What you have gained¶

The same catalogue you'd call from import spectro_kernel is now Claude's toolbox. The agent picks the right tools, explains its choices using the kernel's own metadata, and you keep the audit trail. No new infrastructure beyond spectro-mcp --http.

Going further¶

Hook in a custom prompt that biases Claude towards your preferred workflows (e.g. "always run compare_normalisations before measuring a line").
Wrap the agent in a periodic task (cron + a Claude API call) for nightly monitoring - Be-star variability alerts, aurora amplitude history, exoplanet RV drift.
Pair with the web playground for human-in-the-loop debugging when the agent picks the wrong tool.