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) — using either OAuth sign-in or a Bearer API key (see OAuth connector mode below) — 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.

OAuth connector mode

Noveum's MCP server is also an OAuth 2.1 authorization server. URL-only clients — Cursor, Claude and Claude Code, VS Code, ChatGPT (developer mode), Windsurf, Cline, Replit, Zed, Goose, and any other client that supports the MCP authorization spec — discover this automatically — add just …/api/mcp and the client opens a Noveum sign-in and consent screen instead of asking you for a key. See the Noveum MCP page for per-client install snippets (including Claude Desktop via mcp-remote, cURL, and Python).

Discovery

The MCP server publishes standard OAuth discovery documents so clients never need hardcoded endpoints:

Document	URL
Protected resource metadata	`https://noveum.ai/.well-known/oauth-protected-resource`
Authorization server metadata	`https://noveum.ai/.well-known/oauth-authorization-server`

An unauthenticated request to /api/mcp returns 401 with a WWW-Authenticate: Bearer resource_metadata="https://noveum.ai/.well-known/oauth-protected-resource" header, which is how compliant clients find their way into the flow without any manual configuration.

Scopes

Every OAuth token carries one or more of these scopes, chosen by you on the consent screen. Scopes only ever narrow what a connected app can do — your own role/RBAC permissions in the organization still apply on top.

Scope	What it allows
`noveum.read`	Read projects, traces, datasets, evals, and reports
`noveum.write`	Create and update resources (datasets, jobs, settings)
`noveum.execute`	Start jobs (ETL, evals, NovaPilot, NovaSynth)

Dynamic client registration (DCR)

There's no manual "create an OAuth app" step. MCP clients that support RFC 7591 dynamic client registration register themselves against registration_endpoint (from the authorization server metadata) the first time you connect, then immediately continue into the authorization-code + PKCE flow. You'll only ever see the Noveum consent screen — never a client-setup step.

Org binding

An OAuth token is scoped to exactly one organization, chosen at consent time (auto-selected if you belong to only one; otherwise you'll pick from a selector). It is never inferred from your last-active web session. To connect the same client to a different organization, run the connect flow again and choose that organization on the consent screen.

Revoking access

Every app you've approved shows up under Settings → Connected apps, along with the organization it's scoped to, its granted scopes, and when it was last used. Revoking there immediately invalidates the grant and every access/refresh token issued from it — the connected client loses access on its next request.

API key vs OAuth: which to use

OAuth (default for URL-only setup) — best for interactive assistants like Cursor, Claude, and ChatGPT where a human is present to approve the consent screen once.
Bearer API key — best for headless or scripted clients: CI pipelines, cron jobs, server-to-server integrations, or any MCP client without a browser to complete a sign-in. Use the JSON config with headers.Authorization: Bearer <API key> from the snippets on the Integration page.

Remote MCP in Cursor (OAuth vs Bearer)

Noveum’s MCP endpoint supports two authentication modes: OAuth 2.1 sign-in (for URL-only clients) and a Bearer API key in Authorization (for headless clients). See OAuth connector mode above for how the automatic flow works.

When you configure a remote HTTP MCP server in Cursor, you can either:

URL only — add just the MCP URL (for example …/api/mcp) and Cursor runs the OAuth sign-in and consent flow automatically. Approve it once and you're connected.
URL + Bearer key — add the MCP URL and headers.Authorization: Bearer <your key> in .cursor/mcp.json (or use the in-app Integration one-click install, which encodes both). Use this for scripted setups or when you want to pin a specific key.

What to do: For a normal interactive setup, add the URL and complete the Noveum consent screen. For headless/scripted use, paste the full JSON from the Integration page or merge url plus headers.Authorization, creating an API key under your organization if you do not have one.

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, etl-jobs-dlq (dead-letter), novaeval-jobs, eval-jobs, recommend-scorers-jobs, novapilot-jobs, novapilot-scheduled-jobs, synthetic-runs, synthetic-generation, and traces (async trace ingest) finish the job asynchronously. Poll the documented GET until status is terminal—about 3–5s while work is active and ~15s when idle (NovaEval codegen and synthetic-generation jobs poll at 2s)—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 runs/batches/analytics/generation/analysis rebuild, recommend-scorers).
`noveum://etl-novaeval-codegen-save`	NovaEval codegen → poll → POST /versions to persist mapperCode (UI); optional PUT + run-mapper smoke test; sandbox and tool-name hints.
`noveum://datasets`	Dataset catalog (optional `?limit=…&offset=…&visibility=…&organizationSlug=…&includeVersions=…&includeItemCounts=…` 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=…`; optional `?limit=…&offset=…`).
`noveum://novasynth-runs`	Synthetic runs index (requires `?projectId=…`; optional `?limit=…&offset=…&status=…&personaId=…&scenarioId=…&batchRunId=…`).
`noveum://novasynth-analytics`	Aggregated synthetic run metrics (requires `?projectId=…&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD`).
`noveum://novapilot-schedules`	Scheduled NovaPilot analyses (requires `?projectId=…` on the URI).
`noveum://novapilot-report-markdown`	A completed NovaPilot report rendered as markdown (requires `?reportId=…`).
`noveum://agent-versions`	Deployed agent/service versions seen in traces (requires `?projectId=…`).
`noveum://developer-calls-playbook`	Guided playbook for testing voice agents through the Developer Calls API.

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
`/setup_novasynth`	Full NovaSynth first-time setup: agent config → phone endpoint → generate personas + scenarios (poll) → one test run.	synthetic-generation, then synthetic-runs

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.

Pair with the Noveum Agent Skill

MCP gives your agent the tools; the Noveum Agent Skill gives it the procedure — a seven-step, acceptance-gated playbook for integrating the SDK, verifying trace completeness, building datasets, running evals and NovaPilot, and applying fixes. Install both for the full "AI engineer" experience: the skill tells the agent what to do next, and this server executes each step with always-current schemas.