MCP server: resources, prompts & agents

Connect Claude Code, Codex, Cursor, and VS Code to Noveum tools, resources, prompts, and OAuth.

Once Claude Code, Codex, Cursor, or VS Code is configured with your Noveum MCP URL (…/api/mcp), using either OAuth sign-in or a Bearer API key, the assistant can use 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 such as Claude Code, Codex, Cursor, and VS Code discover this automatically through the MCP authorization spec. Add only …/api/mcp, and the client opens a Noveum sign-in and consent screen instead of asking for a key. ChatGPT developer mode, Windsurf, Cline, Replit, Zed, Goose, and other compatible clients can use the same flow. See the Noveum MCP page for additional 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 such as Claude Code, Codex, Cursor, and VS Code when a human can approve the consent screen once.
Bearer API key: best for headless or scripted clients such as CI pipelines, cron jobs, server-to-server integrations, or any MCP client without a browser. Use the JSON config with headers.Authorization: Bearer <API key> from the Integration page.

Connect your coding agent

Use these clients in this order across Noveum documentation: Claude Code, Codex, Cursor, and VS Code. Noveum supports OAuth 2.1 for interactive use and a Bearer API key for scripted or headless use.

Claude Code

claude mcp add --transport http noveum "https://noveum.ai/api/mcp"

Claude Code starts OAuth after the URL-only server is added. For a Bearer key, use the generated command on the in-app Integration page.

Codex

codex mcp add noveum --url https://noveum.ai/api/mcp
codex mcp login noveum

For Bearer authentication, store the key in an environment variable and register it by name:

export NOVEUM_API_KEY="your-key"
codex mcp add noveum --url https://noveum.ai/api/mcp --bearer-token-env-var NOVEUM_API_KEY

Cursor

OAuth: add only the MCP URL. Cursor discovers OAuth, opens Noveum sign-in, and asks you to approve access.
Bearer key: add the URL and headers.Authorization: Bearer <your key> in .cursor/mcp.json, or use the one-click install from the in-app Integration page.

VS Code

OAuth: install the URL-only configuration from the in-app Integration page and complete Noveum sign-in.
Bearer key: select API key mode on the same page to generate a configuration with the Authorization header.

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 Claude Code / Codex / Cursor / 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 connection steps in Claude Code, Codex, Cursor, and VS Code, see your in-app Integration page. It also includes options for Python, cURL, and other MCP clients.

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.

MCP server: resources, prompts & agents

On this page