> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trainy.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Integration
> Connect Pluto to AI coding assistants like Claude Code via the Model Context Protocol.
**New & Experimental** - MCP support is a new feature. Please report any issues to [support@trainy.ai](mailto:support@trainy.ai) or on [Discord](https://discord.com/invite/HQUBJSVgAP).
# Model Context Protocol (MCP) Integration
The Pluto MCP server allows AI coding assistants to directly query your ML experiment data. This enables powerful workflows like:
* Asking your AI assistant to analyze training runs and identify issues
* Comparing metrics across experiments in natural language
* Debugging failed runs by querying logs and metrics
* Getting insights about your ML experiments without leaving your editor
## What is MCP?
The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that enables AI assistants to securely access external data sources. With Pluto's MCP server, tools like Claude Code can directly query your experiment data, metrics, and logs.
## Setup with Claude Code
### Prerequisites
* A Pluto account with an API key ([get one here](https://pluto.trainy.ai))
* Claude Code CLI installed
### Step 1: Get Your API Key
1. Go to [pluto.trainy.ai](https://pluto.trainy.ai) and sign in
2. Navigate to **Settings > Developers > API Keys**
3. Create a new API key and copy it
### Step 2: Configure Claude Code
Run the following command to add the Pluto MCP server:
```bash theme={null}
claude mcp add pluto --transport http --header "Authorization: Bearer mlps_xxxxxxxxxx" -- https://pluto-mcp.trainy.ai/mcp/
```
Replace `mlps_xxxxxxxxxx` with the API key you copied in Step 1.
You can also manually edit the MCP settings file at `~/.claude/mcp_settings.json`:
```json theme={null}
{
"mcpServers": {
"pluto": {
"type": "http",
"url": "https://pluto-mcp.trainy.ai/mcp/",
"headers": {
"Authorization": "Bearer your-api-key-here"
}
}
}
}
```
If the file doesn't exist, create it. Make sure the JSON is valid - you can verify with `cat ~/.claude/mcp_settings.json | jq .`
### Step 3: Restart Claude Code
After saving the configuration, restart Claude Code for the changes to take effect:
```bash theme={null}
claude
```
You should see the Pluto tools become available. You can verify by asking Claude: "What Pluto projects do I have?"
## Available Tools
Once connected, the following tools become available to your AI assistant.
### Projects, runs, and data
| Tool | Description |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_projects` | List all projects in your organization |
| `list_runs` | Search and filter experiment runs by project, name, or tags. Also accepts `config_filter` (see [Filtering by config](#filtering-by-config-and-system-metadata)) and `konduktor_job_prefix` to find the run(s) for a Konduktor job — pass a full hashed job ID (e.g. `train-model-db87`, returns 0 or 1) or a YAML base name (e.g. `train-model`, returns the whole family). When set, `project_name` is optional and the search scopes to your org. |
| `get_run` | Get detailed information about a specific run. For runs launched on Konduktor, the output includes a labeled **Konduktor Job** block (job name and namespace, accelerator, nodes, GPUs/node, rank, node, restart attempt). |
| `list_metric_names` | List the distinct metric names logged in a project, with optional substring search |
| `query_metrics` | Query time-series metrics (loss, accuracy, etc.). Accepts `step_min` / `step_max` to scope to a [step range](#querying-a-step-range) |
| `query_logs` | Query console logs (stdout/stderr) from a run |
| `get_files` | Get files and artifacts from a run, with presigned download links |
| `get_statistics` | Per-metric count, min, max, mean, standard deviation, and last value |
### Comparing and ranking
| Tool | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `compare_runs` | Compare a metric across multiple runs |
| `get_leaderboard` | Rank the runs in a project by a metric — aggregate by `MIN`, `MAX`, `AVG`, `LAST`, or `VARIANCE` (useful for ranking training stability), ascending or descending |
| `generate_comparison_url` | Build a shareable Pluto web-UI link with a set of runs pre-selected |
### Charts
| Tool | Description |
| ---------------------- | ----------------------------------------------------------------------------------------------- |
| `visualize_metrics` | Render a line chart of one run's metrics as a PNG, returned inline so the assistant can read it |
| `visualize_comparison` | Render a chart overlaying one metric across up to 20 runs |
### Editing runs
| Tool | Description |
| -------------- | -------------------------- |
| `add_tags` | Add tags to a run |
| `remove_tags` | Remove tags from a run |
| `update_notes` | Set or clear a run's notes |
These three tools **modify your data**. A connected assistant can change a run's **tags** and **notes** — and nothing else. It cannot create or delete runs, or alter their config, metrics, or files.
Note that [run groups](/pluto/runs-table#grouping-runs) are expressed as `group:` tags, so editing tags can move a run into or out of a group.
### Filtering by config and system metadata
`list_runs` accepts a **`config_filter`** that filters server-side on any field in a run's config or captured environment. The simplest form is a plain string, ` `:
```
trainer.lr > 0.001
model.name is dit
checkpoint.r2_prefix contains 37a
systemMetadata.gpu_model is H100
```
Keys are dot-paths into the run's **config** by default. Prefix a key with `systemMetadata.` to target the captured environment (GPU model, CUDA version, git branch, hostname, …) instead.
Supported operators: `contains`, `does not contain`, `is`, `is not`, `starts with`, `ends with`, `regex`, `>`, `<`, `>=`, `<=`.
Pass a **list** of conditions to require all of them — conditions always AND together, there is no OR:
```
["model.name is dit", "trainer.lr > 0.001"]
```
`config_filter` reaches `config.*` and `systemMetadata.*` only. To filter on **metric values** (`summaryMetrics.*`), use the [`filters` query language](/pluto/querying-runs#filtering-runs) instead.
### Querying a step range
`query_metrics` and `visualize_metrics` accept **`step_min`** and **`step_max`** (inclusive) to scope a query to a window of steps — handy for zeroing in on a loss spike or an anomaly rather than pulling the whole series:
> "Plot train/loss between steps 4000 and 4500 for run MMP-42"
## Example Prompts
Once configured, you can interact with your Pluto data naturally through your AI assistant:
**List your projects:**
> "What ML projects do I have in Pluto?"
**Find recent runs:**
> "Show me the last 5 training runs in the gpt-finetuning project"
**Analyze a run:**
> "What was the final loss for run 1234? Did it converge?"
**Compare experiments:**
> "Compare the train/loss between runs 100, 101, and 102 - which performed best?"
**Debug failures:**
> "Show me the error logs from run 456 - why did it fail?"
**Get insights:**
> "Are there any anomalies in the metrics for my latest run?"
## Claude Code Web
To make the pluto MCP available to your Claude Code web UI and cloud agents, visit:
[https://claude.ai/settings/connectors?modal=add-custom-connector](https://claude.ai/settings/connectors?modal=add-custom-connector)
From here you can enter the following information for the Pluto MCP server:
* Name: Pluto
* Remote MCP Server URL: [https://pluto-mcp.trainy.ai/mcp](https://pluto-mcp.trainy.ai/mcp)
Afterwards, click on **Connect** and you will be redirected to an OAuth flow where you can enter the Pluto API key you want to use for the MCP connection.
## Feedback
MCP integration is experimental. We'd love to hear your feedback:
* **Discord**: [Join our community](https://discord.com/invite/HQUBJSVgAP)
* **Email**: [support@trainy.ai](mailto:support@trainy.ai)