# Neptune.ai MCP

> Neptune.ai (ML Experiment Tracking) connects your agent directly to your entire machine learning lifecycle. You manage training runs, audit model versions, and inspect deep metrics without manually navigating dashboards. It gives you full, conversational control over your ML projects—from project setup to final model registry.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** mlops, experiment-tracking, model-versioning, training-metrics, data-science, telemetry

## Description

This MCP lets you take complete control of complex machine learning experiments using only natural conversation. Instead of clicking through multiple tabs or exporting raw CSV files just to check a metric, your agent pulls the data directly for you. You can ask it to list all active ML projects and retrieve detailed metadata configurations instantly. Need to audit performance? Your agent searches deeply across historical runs, mapping specific parameters and loss curves. It also keeps track of every model version you promote, ensuring only stable weights are available in the registry. This level of comprehensive visibility into your entire research footprint—all accessible through one unified connection via Vinkius—changes how data science works. You can verify user credentials or deep-dive into a specific project ID to get precise JSON insights on demand.

## Tools

### list_projects
Lists every Neptune workspace and project you have access to in one command.

### get_project
Retrieves the specific configuration and detailed metadata for a single, named ML project.

### search_runs
Searches through all tracked ML experimentation runs inside a designated project to find what you need.

### get_attributes
Pulls detailed parameters and metrics logged during the runtime bounds of any specific experiment run.

### list_models
Shows a list of all trained, packaged models that have been officially logged in your project.

### get_user
Verifies specific user identifiers and confirms the availability status against your service account token.

## Prompt Examples

**Prompt:** 
```
List all training runs for the 'Customer-Churn' project
```

**Response:** 
```
I've retrieved the training history for 'Customer-Churn'. Highlights include 'churn-exp-123' (Accuracy: 0.92), 'churn-baseline' (Accuracy: 0.85), and 5 other recent runs. Would you like to see the loss curve for the top-performing run?
```

**Prompt:** 
```
Show me the metrics for run ID 'churn-exp-123'
```

**Response:** 
```
Retrieving attributes for 'churn-exp-123'… The model achieved a final accuracy of 92.4% with a validation loss of 0.15. Learning rate was set to 0.001. No anomalous gradients were detected during the final epochs. Would you like the full JSON of all 45 logged attributes?
```

**Prompt:** 
```
List all registered models in project 'Fraud-Detection'
```

**Response:** 
```
I've identified 3 promoted models in 'Fraud-Detection': 'XGBoost-Classifier-v2', 'RandomForest-Baseline', and 'NeuralNet-Prod-v1'. All models are mapped to production-ready weights. Which one would you like to inspect for version history?
```

## Capabilities

### View ML Project Scope
List all accessible Neptune workspaces and projects so you know the full boundaries of your work.

### Get Project Details
Pull specific, detailed information about a targeted machine learning project.

### Search Historical Runs
Find and analyze specific training runs or historical checkpoints within any given project.

### Inspect Model Metrics
Extract detailed telemetry, including accuracy metrics and loss curves, from a specific run's checkpoint.

### Manage Registered Models
List and retrieve all trained models that have been officially logged and promoted within the project.

### Audit User Accounts
Verify specific user credentials and confirm account availability details against your active service token.

## Use Cases

### Comparing the Top 3 Models
A researcher needs to compare performance across three different model architectures. Instead of running three separate reports, they ask their agent to search runs and get attributes for all three in one prompt, instantly comparing accuracy and validation loss.

### Debugging a Failed Deployment
An ML engineer finds a deployed model is failing. They use the MCP to list models and then inspect specific project details, pinpointing exactly which version of the code or parameters caused the regression.

### Auditing Project Scope for Compliance
A lead needs to know what ML projects exist across their department. They ask the agent to list all accessible workspaces and projects, getting a complete inventory without speaking to anyone else.

### Retrieving Historical Context
An analyst needs the raw data for an old experiment run from six months ago. They use the MCP to get project details using a specific Project ID and retrieve all associated JSON metadata instantly.

## Benefits

- Stop clicking through dashboards to check metrics. You ask the agent for a run's parameters, and it gives you the exact variables and loss curves instantly.
- Keep track of version control effortlessly. Instead of guessing which model is stable, use the MCP to list and retrieve only those trained models that are marked as production-ready.
- Simplify project visibility. You can quickly enumerate all accessible workspaces and projects, giving you a clear map of your entire ML research footprint in one go.
- Save time auditing credentials. Need to check who has access? Use the agent to verify specific user identifiers against your service account token without manual database queries.
- Deep-dive into data structure. Don't just get numbers; use this MCP to retrieve a precise JSON representation of any Project or Run ID for downstream processing.

## How It Works

The bottom line is you manage complex ML lifecycles conversationally without needing to open a dedicated dashboard.

1. Subscribe to this MCP, then enter your Neptune.ai API Token.
2. Connect the MCP to any compatible client—like Cursor or Claude.
3. Ask your agent a question, like 'Show me all registered models for Project X,' and get an immediate answer.

## Frequently Asked Questions

**How do I find a specific historical run using Neptune.ai (ML Experiment Tracking)?**
You use the `search_runs` tool to filter through all runs within a project. You can then follow up with `get_attributes` to view the deep metrics for that exact run ID.

**What does list_models do in Neptune.ai (ML Experiment Tracking)?**
The `list_models` tool shows you every trained model packaged and logged within your current project, confirming which weights are ready for use or promotion.

**Can I get all the metadata for a whole project?**
Yes. You first need to use `get_project` and provide the specific Project ID. This retrieves detailed information about its setup, boundaries, and associated resources.

**How do I check user permissions with Neptune.ai (ML Experiment Tracking)?**
Use the `get_user` tool. It verifies specific user credentials against your active service account token, confirming who has access to what data within the system.

**Is this MCP only for checking metrics?**
No. While it excels at monitoring training metrics (`get_attributes`), it also handles project visibility (`list_projects`) and model versioning (`list_models`).