MCP

MCP is the platform’s first-class agent surface: an account-aware Model Context Protocol server at /api/mcp/ that shares its services with the REST API and the Console. A coding agent connected to it can inspect health and failures, land and shape datasets, author evaluators and run evals, launch and follow training, schedule optimisation runs, and drive connectors and instrumentation — everything except the steps that need your filesystem, which it hands to the CLI.

Setup

overmind init --ide <client> writes the entry and overmind sync fills in the project key, which is what the Quickstart prompt does for you. The entry is a streamable-HTTP server with an X-Api-Key header:

{
  "mcpServers": {
    "overmind": {
      "url": "https://api.overmindlab.ai/api/mcp/",
      "headers": { "X-Api-Key": "ovr_…" }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "overmind": {
      "type": "remote",
      "url": "https://api.overmindlab.ai/api/mcp/",
      "enabled": true,
      "headers": { "X-Api-Key": "ovr_…" }
    }
  }
}

claude mcp add --scope local --transport http overmind https://api.overmindlab.ai/api/mcp/ --header "X-Api-Key: ovr_…"

Codex takes the same entry in .codex/config.toml. Claude Code keeps the key in local scope (~/.claude.json), outside the repository. Self-hosted: replace the URL with your API host plus /api/mcp/, for example http://localhost:8000/api/mcp/ (overmind init --env local, or --api-url).

Optional plugin

The Cursor, Claude Code and Codex plugins bundle the MCP connection, Overmind branding and the workflow skills. MCP alone is the complete integration: tool descriptions, operating guidance, resources and prompts reach every client, with or without a plugin. Install it from the overmind-core/overmind repository:

Client	Install
Claude Code	`/plugin marketplace add overmind-core/overmind`, then `/plugin install overmind@overmind`
Codex	`codex plugin marketplace add overmind-core/overmind`, then enable Overmind in `/plugins`
Cursor	Add `overmind-core/overmind` as a plugin marketplace, then install Overmind

The plugin’s MCP entry points at the hosted API and signs in with OAuth. The connection reaches every active project your account can access, including projects you join later. For a self-hosted deployment, run overmind init --env local --ide <client> and overmind sync instead. Keep one active Overmind MCP connection per client. Start with list_projects. To see a project in the browser, read overmind://project/current?project_id=ID and open its console_url, which the server builds from FRONTEND_URL. The browser needs its own Console sign-in, and opening a page grants no write access.

Authentication

Account connections. OAuth connections and account API keys find the projects you can access with list_projects. Pass the chosen project_id to every project tool, and as a query parameter on resource URIs. Membership is checked on every operation, and there is no shared “current project”, so parallel work cannot switch another request’s project. Returned resource links keep the project id. Project API keys reach only their own project and can omit project_id. Permissions. Read access exposes the read-only tools; writes need write access. API keys keep their expiry, active-user and IP-allowlist checks, and authenticate as X-Api-Key or Authorization: Bearer. OAuth. A grant asks for overmind:read and/or overmind:write, and needs Console sign-in and explicit consent. Tokens use S256 PKCE, exact redirect matching, one-time codes and resource binding, and only MCP accepts them. Access tokens expire after one hour. A connection stays authorized until it is revoked: refresh tokens have no time limit, but they rotate, and reusing an old one revokes the connection. A disabled account or a lost project membership ends access. Hosting. On a public deployment, set MCP_SERVER_URL to the HTTPS /api/mcp/ endpoint and FRONTEND_URL to the Console. Plain HTTP is accepted only on local loopback. The server then advertises OAuth discovery, public-client registration (token_endpoint_auth_method: none), and the authorization, token and revocation endpoints. To publish the server as an OpenAI app, set OPENAI_APPS_CHALLENGE to the portal’s ownership token; the API serves it at /.well-known/openai-apps-challenge. Transport. Requests are POST with application/json, from an allowed host and origin, within the protocol’s body limit. Authentication failures return 401 and authorization failures 403. Tool errors are structured results: {"error": {code, message, retryable, fields}}. The public surface is read and write only. There are no delete, cancel or generic API tools; retry_deployment is the one lifecycle exception and covers exactly the failed-or-deleted deployment case.

Tools

Thirty-six tools, each with a strict input and output schema the client reads at call time. Every result carries the same object twice — as structuredContent and as compact JSON text — plus resource links for the entities it touched. Arguments marked ? are optional. Project tools also accept project_id, required for account connections. list_projects and get_model_catalog do not need a project.

Projects

Tool	Arguments	Returns
`list_projects`	`limit?`, `offset?`	Authorized active projects, Console/resource links and pagination

Observability

Tool	Arguments	Returns
`inspect_capability_health`	`capability?`, `days?`	Evaluator, live-score, trace-volume, error-rate and latency health
`query_failures`	`capability`, `since_days?`, `limit?`	Recent scored failures for one capability
`query_traces`	`capability?`, `session?`, `search?`, `trace_id?`, `span_id?`, `name?`, `operation?`, `service_name?`, `span_type?`, `status?`, `status_code?`, `has_error?`, `model?`, `has_model?`, `start_time_ns__gte?`, `start_time_ns__lte?`, `min_duration_ms?`, `max_duration_ms?`, `start_after?`, `start_before?`, `total_tokens_gte?`, `total_tokens_lte?`, `total_cost_gte?`, `total_cost_lte?`, `all_spans?`, `unbound?`, `ordering?`, `limit?`, `offset?`, `cursor?`	Traces with bounded cursor or offset pagination
`query_task_executions`	`capability?`, `behaviour?`, `binding_source?`, `trace_id?`, `status?`, `started_after?`, `started_before?`, `min_duration_ms?`, `max_duration_ms?`, `has_error?`, `service_name?`, `operation?`, `span_type?`, `status_code?`, `model?`, `has_model?`, `total_tokens_gte?`, `total_tokens_lte?`, `total_cost_gte?`, `total_cost_lte?`, `limit?`, `offset?`	Behaviour-keyed task executions
`get_job`	`kind`, `id`	A normalized status snapshot for one job

Datasets

Tool	Arguments	Effect
`list_datasets`	`capability?`, `intent?`, `state?`, `search?`, `limit?`, `offset?`	List project datasets
`inspect_dataset`	`dataset`, `chat_limit?`	One dataset: cell chain, sample, recent agent chat, next actions
`query_dataset`	`dataset`, `sql`, `cell?`, `limit?`	Read-only SQL over one ran cell
`create_dataset_from_traces`	`name`, `trace_ids?`, `filters?`, `search?`, `limit?`, `intent?`, `capability?`, `split?`	Land a dataset, one row per trace; the selection is counted first and refused when empty. `split` lands disjoint `<name> train` and `<name> eval` datasets instead of one with an intent. Returns a task receipt
`message_dataset_agent`	`dataset`, `message`	Queue one agent turn for an idle dataset. Returns a job receipt
`run_dataset`	`dataset`, `proposal_cell?`	Run the dataset, optionally accepting one proposal. Returns a job receipt

Evaluation

Tool	Arguments	Effect
`check_evaluation_readiness`	`dataset`, `eval_set?`, `cell?`, `version?`, `mode?`, `variants?`, `judge_model?`	Dataset, active eval set, evaluator applicability, variable bindings, credit readiness
`create_eval_set`	`name`, `evaluator_ids`, `capability?`	Atomically create an eval set and its members in their applicable roles; does not activate it or launch a run
`upsert_evaluator`	`evaluator?`, `name?`, `kind?`, `capability?`, `scope?`, `score_type?`, `display_name?`, `description?`, `rubric_md?`, `evaluation_prompt?`, `checklist?`, `judge_model?`, `score_min?`, `score_max?`, `pass_threshold?`, `requires_reference?`, `variable_mapping?`, `config?`, `applicable_roles?`, `surface?`, `choices?`	Create or update an evaluator
`run_evaluation`	`name`, `dataset`, `eval_set?`, `cell?`, `version?`, `evaluator_ids?`, `variants?`, `max_items?`, `sampling?`, `judge_model?`	Create and launch an eval run. Returns a job receipt
`compare_evaluations`	`run`, `baseline`	Compare a run with a project-scoped baseline
`annotate_evaluation_sample`	`annotation?`, `sample?`, `evaluator?`, `value?`, `label?`, `note?`	Create or update a human annotation, attributed to the key’s owner

Training and serving

Tool	Arguments	Effect
`get_model_catalog`	`has_tool_calling?`, `max_context?`	Models available for fine-tuning: tiers, context limits, training methods, tool-calling, batch bounds
`check_finetune_readiness`	`dataset`, `capability?`, `cell?`, `version?`	Prerequisites, train/eval dataset shape, recommended models, evaluators, credits
`estimate_finetune`	`dataset`, `base_model`, `n_epochs?`, `use_lora?`, `cell?`, `version?`	Real-token cost and duration estimate; creates nothing
`start_finetune`	`dataset`, `base_model`, `capability?`, `eval_dataset?`, `eval_set?`, `validation_dataset?`, `cell?`, `version?`, `eval_cell?`, `eval_version?`, `validation_cell?`, `validation_version?`, `validation_enabled?`, `validation_split_ratio?`, `split_method?`, `name?`, `use_case?`, `hyperparameters?`, `group_id?`, `baseline_model?`, `eval_judge_model?`, `eval_incumbent_before?`, `eval_incumbent_after?`, `eval_model_before?`, `eval_model_after?`	Validate and queue a training job. `baseline_model` overrides the capability’s benchmark for this job; the `eval_*` flags choose which comparison evaluations run. Returns a job receipt
`prepare_training_data`	`dataset`, `base_model`, `context_length`, `training_type?`, `validation_dataset?`, `cell?`, `retry_failed?`	Run exact tokenization for a model and context length; returns a cached preparation report. Poll with `get_job(kind="training_preparation")`
`retry_deployment`	`deployment`	Retry a failed or deleted deployment. Returns a job receipt
`set_active_model`	`capability`, `deployment?`	Verify a ready deployment, then switch the alias; poll the returned `model_activation` job. Omit deployment to clear routing
`set_benchmark_model`	`capability`, `deployment?`	Choose a ready trained deployment as the capability’s default training benchmark; omit deployment to use the codebase incumbent. Does not change serving
`run_inference`	`deployment`, `messages`, `temperature?`, `max_tokens?`	One chat completion against a ready deployment using production output budgets, with usage, latency and finish reason
`get_model_swap_prompt`	`finetune`, `pin?`	A copy-paste prompt that points the capability’s code at a successful fine-tune; the agent applies it locally

run_inference uses the production serving output reservation when max_tokens is omitted or null (currently 8,192 tokens). Explicit positive integer budgets have no MCP-specific ceiling. The model server validates the templated input plus reserved output against the deployment’s context; an oversized request returns context_length_exceeded without silently reducing its budget. Generation exhaustion is reported by finish_reason and truncated. The MCP response’s content is separately bounded to 32,000 characters, with content_clipped indicating any response clipping.

Optimisation

Tool	Arguments	Effect
`check_optimizer_readiness`	`capability`, `dataset?`, `eval_set?`, `cell?`, `version?`, `mode?`, `model_ids?`	Dataset, eval set, model, credit and plan readiness
`start_optimizer`	`capability`, `dataset`, `eval_set?`, `cell?`, `version?`, `mode?`, `model_ids?`, `entrypoint?`, `code_trigger?`, `num_iterations?`, `num_candidates_per_iteration?`, `max_iterations_without_improvement?`	Schedule an optimize, model-comparison or hybrid experiment; drive it with `overmind optimise`. Returns a job receipt
`inspect_optimizer_result`	`experiment`, `max_iterations?`, `max_candidates_per_iteration?`	Iteration scores, candidate patches, winner state, next action

Connectors

Tool	Arguments	Effect
`inspect_connectors`	`connector?`, `include_source_projects?`, `preview?`, `preview_source_project_id?`, `preview_lookback_days?`, `max_runs?`	List or inspect connectors: configuration, mappings, provider capabilities, sync status
`configure_connector`	`connector`, `source_project_id?`, `lookback_days?`, `backfill_from?`, `backfill_to?`, `capability_mapping?`, `auto_sync_enabled?`, `poll_interval_seconds?`, `confirm_mapping?`	Save source project, lookback, capability mapping and polling settings; `confirm_mapping` confirms the reviewed mapping
`sync_connector`	`connector`	Queue the configured import. Returns a task receipt

A connector is created with its provider credentials through overmind connector add or the Console under Integrations; until then the tools answer with the connector_setup_required action.

Instrumentation

Tool	Arguments	Returns
`get_instrumentation_plan`	`capability?`, `behaviour?`	The registered placement tickets for a capability or behaviour
`verify_instrumentation`	`capability?`, `trace_id` or `spans`	Bind and grade an ingested trace by id, or a caller-supplied span list, without writing traces or scores

Jobs

Background work returns a job receipt — kind, id, status and an overmind://jobs/{kind}/{id} resource — that get_job reads back. Kinds: dataset_run, connector_sync, eval_run, training_preparation, finetune (alias finetune_job), optimizer (aliases optimizer_run, optimizer_experiment), deployment and model_activation. Names resolve within the project: capability arguments take an id, key or name; connectors take an id or name; dataset tools prefer the UUID list_datasets returned because dataset names are not unique.

Prompts

Twelve prompts compose the tools into multi-step workflows with human checkpoints:

Prompt	Arguments	What it drives
`investigate-capability`	`capability`	Health, failures, traces and instrumentation evidence
`instrument-repository`	`capability?`	Turn the instrumentation plan into a project- or capability-scoped repository change and verify the spans
`prepare-evaluation`	`dataset`, `eval_set`	Dataset, evaluator, eval-set, binding and credit readiness
`evaluate-change`	`dataset`, `baseline`	Run an eval and compare it with a baseline
`finetune-capability`	`capability`, `dataset`	Check, estimate and launch a training job
`optimize-capability`	`capability`, `dataset`	Check readiness, schedule and inspect an optimisation run
`compare-models`	`capability`, `dataset`, `model_ids`	A bounded model-comparison run and its measured winner
`ship-model`	`capability`, `deployment`, `finetune`	Verify a deployment, activate the model, hand off the repository rollout
`upload-dataset-file`	`path`, `intent?`, `project_id?`	`overmind dataset upload` in the terminal, then verify through MCP
`export-dataset`	`dataset`	`overmind dataset export` to the local filesystem
`download-checkpoint`	`deployment`	`overmind model download-checkpoint` to the local filesystem
`connect-traces`	`connector_type`	`overmind connector add` in the terminal, then configure, confirm the mapping and sync through MCP

Resources

Read-only project entity state under overmind://. Account connections add ?project_id=ID; follow returned links to preserve scope. Static:

URI	Content
`overmind://project/current`	The authenticated project identity, provenance, safe metadata and ordinary `console_url`
`overmind://dataset-upload`	CLI guidance for uploading local dataset bytes
`overmind://dataset-export`	CLI guidance for downloading a committed dataset
`overmind://checkpoint-download`	CLI guidance for downloading an archived checkpoint
`overmind://connector-setup`	CLI guidance for `overmind connector add` — provider keys never cross MCP

Templates: overmind://capabilities/{capability}, overmind://traces/{trace_id}, overmind://sessions/{session}, overmind://datasets/{dataset}, overmind://eval-runs/{eval_run}, overmind://eval-sets/{eval_set}, overmind://finetunes/{job_id}, overmind://deployments/{deployment}, overmind://optimizer-runs/{experiment}, overmind://connectors/{connector}, overmind://jobs/{kind}/{id}. Deployment resources accept ?period=1h|24h|7d|30d|all&source=application|all (defaults: all time and all traffic). For example, overmind://deployments/{deployment}?period=24h&source=application returns the selected metrics and activity, including failures and end-to-end response percentiles, from the same services used by the Console. Each deployment resource also includes a current worker section: state (warm, warming, asleep, or unknown), measurement available, runner/input/backlog counts and recent-activity/warming signals. These use the Console’s cached measurements and do not wake the model. Worker state is independent of the historical metrics filters, deployment readiness (status) and the capability’s routing selection (active_model). Unavailable counts are null, not zero; recent successful traffic can still establish warmth when provider measurements are unavailable.

The CLI boundary

Three things never cross MCP: file bytes, repository edits, and provider secrets. A dataset file goes up with overmind dataset upload; a dataset or checkpoint comes down with overmind dataset export and overmind model download-checkpoint; repository discovery is /overmind setup then overmind sync; an optimisation run’s candidates are generated and replayed by overmind optimise in your checkout; a model swap is a prompt (get_model_swap_prompt) the agent applies with its own editing tools; a connector’s provider key is entered with overmind connector add in a terminal. The prompts above name the exact command at each handoff, and --json on the CLI returns the ids the agent needs to continue.

Workflow skills

overmind init installs the workflow skills next to the MCP entry, and the optional plugin bundles the same files. The main overmind skill covers setup, repository discovery and work that spans several surfaces. Each focused skill covers one surface:

Skill	Workflow
`overmind-agent`	Capability map, behaviour coverage and repository provenance
`overmind-observability`	Trace investigations, failures, latency and instrumentation gaps
`overmind-datasets`	Data Workshop preparation, proposals, generation and export
`overmind-evaluations`	Evaluators, eval sets, runs and baseline comparisons
`overmind-optimiser`	Prompt and code experiments, and model comparisons
`overmind-training`	Exact data preparation, costs, fine-tuning and held-out evaluation
`overmind-inference`	Serving metrics, worker state, live routing and activation
`overmind-integrations`	Tracing providers, boundary mappings and verified imports

overmind skills list --verbose prints the installed catalog. overmind skills sync <names> --ide <client> refreshes the named skills, and overmind init --ide <client> installs the full set. /overmind onboard, setup, ensure-tracing, dataset, finetune, optimise and backtest load the main skill’s references: Cursor through command files, Claude Code through the skill itself. In OpenCode and Codex, ask for the step by name. The main skill is the only place the local scan (/overmind setup) lives; the native prompts cover the server-side workflows.

Overview

Tracing

Core

Agent Testing

Model training

Agents & CLI

Platform

Setup

Optional plugin

Authentication

Tools

Projects

Observability

Datasets

Evaluation

Training and serving

Optimisation

Connectors

Instrumentation

Jobs

Prompts

Resources

The CLI boundary

Workflow skills

​Setup

​Optional plugin

​Authentication

​Tools

​Projects

​Observability

​Datasets

​Evaluation

​Training and serving

​Optimisation

​Connectors

​Instrumentation

​Jobs

​Prompts

​Resources

​The CLI boundary

​Workflow skills

Setup

Optional plugin

Authentication

Tools

Projects

Observability

Datasets

Evaluation

Training and serving

Optimisation

Connectors

Instrumentation

Jobs

Prompts

Resources

The CLI boundary

Workflow skills