MCP server
Connect an MCP client to Noveum, choose OAuth or API-key authentication, and use the supported tools, resources, and guided workflows safely.
Connect an MCP client to https://noveum.ai/api/mcp with either OAuth sign-in or a Bearer API key. The assistant can then use Noveum's registered prompts and resources plus an allowed subset of the live API. Routes that reveal credentials or secrets, provider webhooks, API-key/authentication/OAuth routes, payment, upload and onboarding routes, and the /api/admin path family are excluded from MCP tools. Two credential setup routes and the narrowly scoped NovaSynth Conversation Sync ingest route are deliberate exceptions, described under Security boundary.
The publication manifest declares registry identity ai.noveum/noveum, version 1.0.0, schema date 2025-12-11, website https://noveum.ai/en/mcp, and remote transport streamable-http. Runtime serverInfo is noveum version 1.0.0, and the publish workflow requires the manifest and runtime versions to match. This code contract does not by itself prove that a registry listing is currently live.
To get connected, start with API key vs OAuth. Then review what the server exposes, the security boundary, and the available registered prompts.
Choose authentication
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.
Both choices authorize the same MCP server surface. Organization membership and role permissions still limit what the connection can access.
OAuth connector mode
Noveum's MCP server also implements OAuth 2.1. URL-only clients that support the MCP authorization spec can discover the flow automatically. Add only https://noveum.ai/api/mcp; the client opens a Noveum sign-in and consent screen instead of asking for a key. Setup instructions are available for Cursor, Claude and Claude Code, VS Code, ChatGPT developer mode, Windsurf, Cline, Replit, Zed, Goose, and Claude Desktop through mcp-remote, plus cURL and Python. Availability of setup instructions is not a dated compatibility guarantee for every client release.
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 Bearer challenge. A simplified example is WWW-Authenticate: Bearer resource_metadata="https://noveum.ai/.well-known/oauth-protected-resource". The runtime can also include error, error_description, and resource_metadata challenge parameters. Compliant clients use the resource metadata URL to discover the flow without manual endpoint configuration.
Scopes
Every OAuth token carries one or more of these scopes. The client requests a scope set; the consent screen displays that set, and the user approves or denies it as a whole while choosing an organization. The screen does not provide per-scope checkboxes. Scopes only narrow what a connected app can do; the user's organization role and permissions still apply.
| 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.
Bearer API key
The MCP connection uses the same Bearer API key as the REST API. Create or rotate keys under Organization → API keys, then send the selected key as headers.Authorization: Bearer <API key>. The key belongs to one organization and inherits the permissions of that organization context.
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 | A filtered set of OpenAPI-derived HTTP actions (GET/POST/…) your client invokes with its connected OAuth token or API key - kick off jobs, read catalogs, and poll progress. |
| Docs search | search_noveum_docs retrieves registered workflow, prompt, and resource documentation for a plain-language question. |
| 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 that spell out which tools to chain, what to poll, and when to stop. A client may choose to render them as slash commands. |
Registered prompts bundle curated instructions, and tools call Noveum's HTTP API with the connected credentials. For a long-running action, retain the returned run ID and poll the supplied status endpoint until the response reports a terminal state.
Recommended workflow
- Load resources first (projects, trace filters, scorers, and datasets) so every id and slug comes from real data - not guesses.
- Use tools for API calls: list things, start jobs, and read results. Pass
projectIdororganizationSlugwhen a tool asks for them. - When an action is long-running, use the run ID or status URL in its kickoff response and poll that status endpoint until it reaches a terminal state. Honor any retry guidance returned by the API.
- Optional: use registered prompts for guided workflows. Clients that expose prompt selection as slash commands may show the registered name with a leading slash.
Security boundary
MCP does not expose routes that reveal credentials, return webhook or sync secrets, manage API keys, create or update evaluation providers, perform authentication or OAuth operations, take payments, use the upload service, run onboarding, or use the /api/admin path family. Provider-specific NovaSynth webhooks for VAPI, Retell, and Pipecat are also excluded because they require HMAC-signed delivery from those providers.
Two credential routes are exposed so an assistant can finish a setup you asked for. Both are POST only and check the caller's normal permission:
| Route | Use | Permission |
|---|---|---|
POST /api/v1/providers/test-connection | Test evaluation provider credentials. Changing a stored provider's Base URL or Endpoint still requires a new API key. | providers:write |
POST /api/v1/novasynth/agent-endpoints/{id}/rotate-credentials | Replace the stored secrets of a NovaSynth test connection. | synthetic:write |
There is one deliberate webhook-style exception:
POST /api/v1/novasynth/conversation-sync/{projectId}/{token}This tool accepts a Conversation Sync payload for an existing NovaSynth configuration. The MCP connection still requires its normal OAuth token or API key. The target configuration is additionally selected and authenticated by the token path value; an organization API key does not replace that path token. MCP can use the route only when the caller already knows both the project ID and sync token - it cannot reveal or regenerate the token.
The complete Conversation Sync URL is a secret because it contains the token in its path. A client, proxy, or request log may retain tool arguments or URLs. Use this tool only from a trusted MCP client for an explicit test or recovery workflow. For normal ongoing delivery, configure the external integration directly. Never paste the token into a prompt, commit it, or store it in shared MCP configuration. If it is exposed, regenerate the token with POST /api/v1/novasynth/agent-config/regenerate-sync-token?projectId=<project-id> and update every integration that used the previous URL.
See Agent configuration for the payload, webhook URL, token controls, and regeneration behavior.
Ask the docs: search_noveum_docs
search_noveum_docs is a read-only tool that answers a natural-language question with the
documentation behind it. It searches one corpus built from the server's own registrations:
the background-work guide (queues, poll intervals, terminal statuses), every registered
prompt playbook, and every noveum:// resource, including the three static playbooks in
full. Because the corpus is derived from those registrations rather than copied, it follows the registered server surface.
| Argument | Purpose |
|---|---|
query | The question, in plain language: "how do I start a NovaSynth batch and wait for it". |
source | Optional. Narrow to guide, prompt, or resource. |
limit | Optional. How many documents to return (1-10, default 3). |
Each result carries the document's title, its reference (the registered prompt or noveum://
URI it came from), a relevance score, and the documentation text itself. When nothing
matches, the tool returns the catalog it searched, narrowed to source when you set one,
so the agent can browse rather than guess.
Reach for it before a workflow you have not run before, when a job's poll interval or terminal statuses matter, or when you need the exact endpoint sequence for a NovaSynth, ETL, eval, or NovaPilot task.
Resources
Resource catalog (read-only JSON)
| URI | Purpose |
|---|---|
noveum://projects | Projects visible to the connected OAuth token or API key. |
noveum://filter-values | Trace filter enums (projects, environments, statuses, …). Add optional projectId to scope every value to one project. |
noveum://scorers | Built-in and custom scorers for evaluations. |
noveum://org-status | Organization usage, limits, and API status snapshot. |
noveum://worker-workflows | Status guidance for supported long-running workflows. |
noveum://etl-novaeval-codegen-save | Guided workflow for generating, reviewing, saving, and testing an ETL mapper. |
noveum://datasets | Organization dataset catalog. Optional query parameters: limit, offset, visibility, organizationSlug, includeVersions, and includeItemCounts. |
noveum://eval-jobs | Organization eval-job catalog. Add optional projectId to narrow it. |
noveum://etl-jobs | Organization ETL-job catalog. Add optional projectId and environment filters. |
noveum://novasynth-batch-runs?projectId=… | NovaSynth batch runs for one project. projectId is required; limit and offset are optional. |
noveum://novasynth-runs?projectId=… | NovaSynth runs for one project. Optional filters are limit, offset, status, personaId, scenarioId, and batchRunId. |
noveum://novasynth-analytics?projectId=…&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD | NovaSynth analytics for one project and inclusive date range. All three query parameters are required. |
noveum://novapilot-schedules?projectId=… | NovaPilot schedules for one project; projectId is required. |
noveum://novapilot-report-markdown?reportId=…&projectId=… | Render one completed NovaPilot report as Markdown. Both IDs are required. |
noveum://agent-versions?projectId=… | Unique service_version values for one project; projectId is required. |
noveum://developer-calls-playbook | Guided playbook for testing voice agents through the Developer Calls API. |
Fixed resources use the URI shown in the table. Query-aware resources accept the listed parameters in any order through their registered URI template; include every parameter marked required. Use an OpenAPI-derived tool for mutations or for a read parameter not listed here.
Registered prompts
Registered prompt catalog
| Prompt | Purpose |
|---|---|
debug_traces | Find error traces, inspect spans, and summarize likely root causes. |
setup_etl_pipeline | Create an ETL job, generate and review its mapper, then start and monitor an ETL run. |
generate_etl_mapper_novaeval | Generate, review, and save an ETL mapper. |
run_evaluation | Start an evaluation and monitor its status. |
analyze_with_novapilot | Start NovaPilot analysis and retrieve the completed report. |
optimize_costs | Review organization and project usage and cost signals. |
trace_error_triage | Group recent error traces and summarize likely root causes. |
compare_eval_runs | Compare two completed evaluation runs for the same job. |
recommend_scorers_for_dataset | Request scorer recommendations for a dataset and retrieve the result. |
dataset_publish_review | Explain a dataset version diff before publication. |
project_health_snapshot | Summarize project health, weak scorers, and follow-up recommendations. |
etl_run_postmortem | Diagnose a failed ETL run and sample related traces. |
novapilot_schedule_overview | Inspect scheduled NovaPilot reports and active run status. |
novasynth_flaky_scenarios | Find high-variance scenarios across synthetic batches. |
start_novasynth_batch | Start a NovaSynth batch and monitor it until it reaches a terminal state. |
setup_novasynth | Guide first-time setup from agent configuration through a one-pair test run. |
run_novasynth_inbound_batch | Have your outbound bot dial every run of an inbound batch, one call at a time: claim, dial once ready, wait for the result, and retry expired runs twice. |
test_voice_agent | Run one Developer Calls API test and return its status, evaluation, transcript summary, recording URL, and exportable configuration. |
full_agent_improvement_cycle | Chain trace review, ETL, evaluation, NovaPilot recommendations, and a next-version verification plan. It does not edit or deploy the application. |
compare_agent_versions | Compare trace count, errors, latency, and available NovaPilot evidence for two deployed service versions. |
download_novapilot_report_markdown | Retrieve a completed NovaPilot report as copyable Markdown. |
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.
Older material may use Noveum Scale as a discovery term for production operation plus this MCP connection. It is not a separate product. Use noveum-trace production configuration for sampling and delivery, and this page for the MCP server.
Troubleshooting
Authorization or organization mismatch
OAuth tokens are bound to the organization selected during consent, and API keys belong to the organization that issued them. If a known project or dataset is missing, confirm the connected identity's role and organization. Reconnect OAuth to choose another organization, or replace the Bearer key with one from the intended organization.
Stale tool or resource discovery
Refresh the MCP server in the client after reconnecting, changing credentials, or receiving a server update. If the client still shows an old tool or resource catalog, start a new MCP session so it performs discovery again.
Query-aware resource URI rejected
Use the registered URI template and include every required query parameter in the URI itself. For example, NovaSynth analytics needs projectId, startDate, and endDate; a value supplied only in prose or as an unrelated tool argument does not complete the resource URI.
Queued job has no result yet
A successful kickoff can mean the job is queued, not completed. Keep the returned run ID or status URL and poll the documented status endpoint until it reaches a terminal state. Honor retry guidance, and do not start a duplicate job merely because the first poll is still queued.