MCP server: resources, prompts & agents

How Noveum’s MCP server exposes tools, read-only resources, slash prompts, and polling—use this with Cursor, VS Code, or any MCP client.

Once your editor is configured with your Noveum MCP URL (…/api/mcp) and a Bearer API key, the assistant uses the same capabilities as the Noveum app.

How Noveum’s MCP agents work

Load resources first (projects, trace filters, scorers, datasets; noveum://etl-novaeval-codegen-save for AI mapper codegen + saving to DB; noveum://worker-workflows for poll cadences) so every id and slug comes from real data—not guesses.
Use tools for API calls: list things, start jobs, and read results. Pass projectId or organizationSlug when a tool asks for them.
When a job is long-running, the API returns an id immediately. Poll the matching status endpoint until the status is final—about every 3–5 seconds while work is active, or ~15 seconds when idle.
Optional: use slash prompts for guided workflows (traces, ETL, evals, NovaPilot, NovaSynth, and more).

API key

The MCP connection uses the same Bearer API key as the REST API. Rotate keys from your organization → API keys when needed.

What the MCP server gives you


Tools	OpenAPI-derived HTTP actions (GET/POST/…) your client invokes with the Bearer token—kick off jobs, read catalogs, poll progress.
Resources	Read-only JSON at `noveum://` URIs—load these before planning so ids, slugs, and filter enums come from real data.
Prompts	Registered workflow prompts (slash commands) that spell out which tools to chain, what to poll, and when to stop.

Slash commands bundle curated instructions. Tools call Noveum’s HTTP API with your API key. Heavy work runs in background workers—agents poll status endpoints until a terminal state, on the same cadences the web app uses.

How agents wait for work

A kickoff response returns an id immediately; BullMQ workers on queues such as etl-jobs, novaeval-jobs, eval-jobs, recommend-scorers-jobs, novapilot-jobs, novapilot-scheduled-jobs, synthetic-runs, and synthetic-generation finish the job asynchronously. Poll the documented GET until status is terminal—about 3–5s while work is active and ~15s when idle—matching Noveum’s UI.

End-to-end flow (Mermaid)

flowchart LR
    User["User in Cursor / Claude / VS Code"] -->|slash command| Prompt
    Prompt -->|chains| Tools
    Tools -->|HTTP Bearer API key| NoveumApi["Noveum /api/v1/*"]
    NoveumApi -->|enqueues| Queue["BullMQ queue (etl-jobs, eval-jobs, novapilot-jobs, synthetic-runs, ...)"]
    Queue --> Worker["Worker (apps/workers/src/*)"]
    Worker -->|updates status| NoveumApi
    Tools -->|poll status every 3-5s until terminal| NoveumApi
    Resources["MCP Resources (read-only JSON)"] --> Prompt
    NoveumApi --> Results
    Results --> User

Paste the diagram into a Mermaid viewer if your docs renderer does not draw it.

Resources we expose (read-only JSON)

URI	Purpose
`noveum://projects`	Projects visible to this API key.
`noveum://filter-values`	Trace filter enums (projects, environments, statuses, …).
`noveum://scorers`	Built-in and custom scorers for evaluations.
`noveum://org-status`	Organization usage, limits, and API status snapshot.
`noveum://worker-workflows`	Static playbook: queues, poll URLs, intervals, terminal statuses (ETL+NovaEval, eval, NovaPilot, NovaSynth).
`noveum://etl-novaeval-codegen-save`	NovaEval codegen → poll → POST /versions to persist mapperCode (UI); sandbox and tool-name hints.
`noveum://datasets`	Dataset catalog (optional limit, offset, visibility, … on the URI).
`noveum://eval-jobs`	Eval job catalog (optional `?projectId=…` on the URI).
`noveum://etl-jobs`	ETL job catalog (optional `?projectId=…&environment=…`).
`noveum://novasynth-batch-runs`	Synthetic batch runs list (requires `?projectId=…` on the URI).
`noveum://novasynth-runs`	Synthetic runs index (requires `?projectId=…` on the URI).
`noveum://novapilot-schedules`	Scheduled NovaPilot analyses (requires `?projectId=…` on the URI).

Slash-command prompts

Prompt	Purpose	Worker / notes
`/debug_traces`	Find error traces, inspect spans, summarize root causes.	Reads only; trace ingest uses the traces queue.
`/setup_etl_pipeline`	ETL job + NovaEval mapper (poll) + apply code + trigger + poll ETL run.	novaeval-jobs, then etl-jobs
`/generate_etl_mapper_novaeval`	Queue NovaEval codegen, poll outputCode, POST /versions to set mapperCode.	novaeval-jobs
`/run_evaluation`	Run eval jobs and poll run/status endpoints.	eval-jobs worker
`/analyze_with_novapilot`	Kick off NovaPilot analysis and poll the report.	novapilot-jobs worker
`/optimize_costs`	Review org/project usage and cost signals.	Read-only (status + usage APIs)
`/trace_error_triage`	Group recent error traces and likely root causes.	Reads only; ingest still async on traces queue.
`/compare_eval_runs`	Diff two completed eval runs for the same job.	Reads only
`/recommend_scorers_for_dataset`	Start scorer recommendation and poll until done.	recommend-scorers-jobs queue
`/dataset_publish_review`	Explain dataset version diff before publish.	Reads only
`/project_health_snapshot`	Project health plus worst scorers and fixes.	Reads only
`/etl_run_postmortem`	Diagnose a failed ETL run and sample related traces.	etl-jobs worker (poll runs if still active)
`/novapilot_schedule_overview`	Inspect scheduled NovaPilot runs and poll active rows.	novapilot-scheduled-jobs worker
`/novasynth_flaky_scenarios`	Find high-variance scenarios across batch synthetic runs.	synthetic-runs worker (poll batches if needed)
`/start_novasynth_batch`	POST a new batch run and poll it until terminal.	synthetic-runs worker

For per-editor connection steps (Cursor install links, Claude CLI, VS Code, Windsurf, ChatGPT), see your in-app Integration page or the vendor docs linked from there.

MCP server: resources, prompts & agents

How Noveum’s MCP agents work

API key

What the MCP server gives you

Get Early Access to Noveum.ai Platform

On this page