---
title: "Startup Validation MCP Server for Claude, Cursor & Codex"
slug: mcp
description: "Startup validation API and remote MCP server. Score any idea from 60+ live sources inside Claude, Cursor, Codex or Hermes, in one tool call. Start free."
canonical: https://preuve.ai/mcp
---

# Preuve MCP server and Agent API

**Only 17.5% of ideas earn a go.** Find out where yours stands, with market research and cited evidence inside your agent.

Get a viability score, market sizing and a shareable report. Five MCP tools for your own ideas, including free idea generation, plus `get_agency` and a `workspace` switch for client work on a Consultant or Agency workspace. Usage draws from your existing Preuve plan, so there is no separate API fee.

## Install

Server URL: `https://mcp.preuve.ai/mcp` (remote, Streamable HTTP).

**Fastest, and the same message for every client: paste one prompt.** Get a key at https://preuve.ai/app?settings=apiKeys (creating a key by hand there is self-serve on a paid personal plan or in an active Consultant or Agency workspace), replace `prv_your_key` with it, and hand your agent this:

```
Set up Preuve AI MCP for me.

Server: https://mcp.preuve.ai/mcp (HTTP transport)
Auth header: Authorization: Bearer prv_your_key

Read https://docs.preuve.ai/mcp-server.md for the setup that matches
this client, and https://docs.preuve.ai/agent-skill.md for how to use
the tools without spending paid quota. Install the skill if you can.

Then run start_analysis with scanType "starter" on this idea:
<describe your idea>
```

The agent reads the two doc pages, picks the setup that matches its own client, installs the Agent Skill if it supports skills, then runs a free starter scan. Nothing below is required if you use it.

**By hand, in Claude Code, Cursor, Codex, Hermes, or any HTTP MCP client.** With the same key:

```bash
claude mcp add preuve --transport http https://mcp.preuve.ai/mcp \
  --header "Authorization: Bearer prv_YOUR_KEY"
```

Hermes Agent reads the same server from its config.yaml:

```yaml
mcp_servers:
  preuve:
    url: "https://mcp.preuve.ai/mcp"
    headers:
      Authorization: "Bearer prv_YOUR_KEY"
```

**claude.ai, web or desktop.** One-click install from the Claude Connectors Directory: https://claude.ai/directory/preuve-ai. Or add a custom connector pointing at `https://mcp.preuve.ai/mcp`. Either way, sign-in and consent happen in the browser and the key is issued automatically, so there is nothing to copy, and it works on any plan including free. Start free: connect and run your first starter scans. Revoke the key anytime from https://preuve.ai/app?settings=apiKeys.

**Local stdio**, only if your client cannot speak remote HTTP MCP. Ask vincent@preuve.ai for `preuve-mcp-server.mjs` (one Node file), then:

```bash
claude mcp add preuve --env PREUVE_API_KEY=prv_YOUR_KEY \
  -- node /path/to/preuve-mcp-server.mjs
```

### Verify

List your MCP tools. Six `preuve` tools should appear: five for your own ideas, plus `get_agency` for client work on a Consultant or Agency workspace, which is also what `workspace: "agency"` on `start_analysis` / `get_analysis` / `export_analysis` acts on. All six are advertised to every client, so seeing `get_agency` on a personal account is normal. An Agency call gives `403 INSUFFICIENT_SCOPE` when the KEY lacks `agency:read` / `agency:write` (the default for a new key, and the only possibility for one created before 2026-09-09), and `404 AGENCY_NOT_FOUND` when the key has the scope but the ACCOUNT belongs to no workspace. Scope is checked first, so a personal key gets the 403, never the 404. Then run a free smoke test:

1. `start_analysis` with `scanType: "starter"` and any idea sentence. Starter scans cost nothing.
2. `get_analysis` with the returned id until `status` is `COMPLETED`.
3. Read the viability score.

## Three rules before your first call

1. **`scanType` is required and explicit.** `starter` is free; `deep` spends the account's paid quota. There is no default, so you cannot spend money by accident. A refused deep scan fails loudly instead of downgrading.
2. **`clientRunId` is the idempotency key.** Re-sending the same value replays the existing run instead of starting a second one. Use it on every retry.
3. **Poll, do not block.** Runs are async: a starter scan takes about 60 seconds, a deep scan about ten minutes.

The tool and endpoint contracts and the error codes are stable.

## MCP tools

| Tool | What it does |
| --- | --- |
| `start_analysis` | Create one run. Requires an explicit `scanType` (`starter`/`deep`) so agents never spend paid quota by accident. To screen several ideas, call it once per idea. |
| `get_analysis` | Poll a run: status, `readyForExport`, enrichment progress, per-module statuses, report and share URLs. |
| `enrich_analysis` | Idempotently generate missing core sections; optionally start deep modules. |
| `export_analysis` | Structured `ideas-json` export (schemaVersion 2) for one completed run. |
| `generate_ideas` | Generate startup ideas from interests. Free accounts get 5 per rolling 24 hours; `pro` (Pro model) and `fit` (founder-profile tailoring) are paid perks. Spends no scan quota or tokens. |

A sixth tool and one shared argument act on a Consultant or Agency
**workspace** rather than your own ideas. They need BOTH a key carrying
`agency:read` / `agency:write` and live workspace membership, checked in that
order: a key without the scope gets `403 INSUFFICIENT_SCOPE`, and a scoped key
on an account with no workspace gets `404`.

| Call | What it does |
| --- | --- |
| `get_agency` | Workspace identity, your role, remaining shared project quota, and the client reports list, dashboard-created ones included. |
| `start_analysis` with `workspace: "agency"` | Create one deep client project against the shared quota. Never falls back to personal credits. |
| `get_analysis` with `workspace: "agency"` | Poll one client report. |
| `export_analysis` with `workspace: "agency"` | Structured JSON for one completed client report. |

The [Agent Skill](https://docs.preuve.ai/agent-skill) teaches an agent to use them well: scan-type quota safety, the start-poll-enrich-export sequence, module caps, and which failures are safe to retry.

## HTTP API

One API key, one header: `x-preuve-key`. No signing, no bearer tokens, no sessions.

| Method | Path | Scope | Purpose |
| --- | --- | --- | --- |
| POST | `/api/agent/analyses` | `analysis:write` | Start one analysis (starter or deep) |
| GET | `/api/agent/analyses/:id` | `analysis:read` | Poll one analysis |
| POST | `/api/agent/analyses/:id/enrich` | `analysis:write` | Generate export sections and deep modules |
| GET | `/api/agent/analyses/:id/export` | `export:read` | Export one analysis as JSON |
| POST | `/api/agent/analysis-batches` | `batch:write` | Start up to 5 analyses |
| GET | `/api/agent/analysis-batches/:id` | `batch:read` | Poll a batch |
| GET | `/api/agent/analysis-batches/:id/export` | `export:read` | Export a batch as JSON |
| POST | `/api/agent/tools/idea-generator` | `analysis:write` | Generate startup ideas (backs `generate_ideas`) |
| GET | `/api/agent/agency` | `agency:read` | Workspace identity, role, shared quota, client reports |
| POST | `/api/agent/agency/analyses` | `agency:write` | Start a client project on shared credits |
| GET | `/api/agent/agency/reports` | `agency:read` | List every client report in the workspace |
| GET | `/api/agent/agency/reports/:id` | `agency:read` | Poll one client report |
| GET | `/api/agent/agency/reports/:id/export` | `agency:read` | Export one client report as JSON |

### Start a run

```bash
curl https://preuve.ai/api/agent/analyses \
  -H "x-preuve-key: $PREUVE_API_KEY" \
  -H "content-type: application/json" \
  --data '{"clientRunId":"run-online-001","scanType":"starter","idea":"A workflow automation service for solo founders that validates market demand before they build.","publish":true}'
```

`clientRunId` is the idempotency key: re-POSTing the same value replays the existing run instead of creating a second one.

### Poll response

```json
{
  "id": "run_123",
  "reportId": "report_123",
  "clientRunId": "run-online-001",
  "scanType": "deep",
  "analysisTier": "advanced",
  "status": "COMPLETED",
  "readyForExport": true,
  "enrichment": { "mode": "core", "status": "completed" },
  "modules": {
    "proofOfDemand": { "status": "completed" },
    "founderFit": { "status": "not_generated" },
    "playbook": { "status": "generating" },
    "trends": { "status": "not_generated" },
    "community": { "status": "not_generated" }
  },
  "reportUrl": "https://preuve.ai/app/results?id=report_123",
  "shareUrl": "https://preuve.ai/share/abc123"
}
```

### Run lifecycle

- `PENDING` - the run record exists and is waiting for dispatch.
- `PROCESSING` - the Preuve analysis pipeline is running.
- `COMPLETED` - the report is done; enrich if needed, then export.
- `FAILED` - the run reached a terminal error with a stable code.

### Scopes

- `analysis:write` - create analysis runs and enrich them for the key owner.
- `analysis:read` - poll single-run status, module states, and URLs.
- `batch:write` - create bounded batches up to 5 ideas.
- `batch:read` - poll batch status and child run URLs.
- `export:read` - export completed analyses and batches as JSON.
- `agency:write` - start client projects in the owner's Agency workspace, spending its shared project credits.
- `agency:read` - list, poll and export every client report in that workspace, including reports created in the Agency dashboard.

The two `agency:*` scopes reach the whole workspace rather than the calling account, and they are never granted implicitly: a key created before 2026-09-09, or created since without asking for them, gets `403 INSUFFICIENT_SCOPE` on `/api/agent/agency/**`. Scopes are fixed when a key is created, so recovery means a new grant, and each route has a condition. Reconnecting the client works on any plan including free, but only if that client rebuilds its scope request from our discovery document rather than replaying a cached one. Creating a key by hand works only if you tick "Include Agency workspace access" AND your account may create keys by hand, which means a paid personal plan or membership of a Consultant or Agency workspace with an active subscription.

## Scan types and quota

`scanType` is explicit on every run.

- `starter` runs the Reality Check at no cost from your Starter scan allowance.
- `deep` runs the full paid analysis (15+ sections, pivots, citations) and consumes account quota: subscription scans first, then lifetime monthly scans, then tokens.

An agent can never spend paid quota by accident. A refused deep scan fails loudly instead of silently downgrading. Failed runs refund whatever they claimed. There is no separate API fee.

## Deep modules

Optional add-on generations on paid deep reports, requested through the enrich endpoint. Each module is capped at one successful generation per report and is included in the deep report price.

- `proofOfDemand` (async) - verified real-demand prospects with verbatim quotes. Every quote links to its source thread.
- `founderFit` (inline) - founder-vs-plan underwriting from a submitted founder profile: fit score, top risks, pivot fit.
- `playbook` (async) - a concrete launch playbook generated for the validated idea.
- `trends` (async) - Google Trends data for the idea, generated on demand; the analysis never fetches it on its own.
- `community` (async) - community signals: real discussions from forums, Reddit, review sites, and X about the market, generated on demand; the analysis never fetches it on its own.

## What a key can and cannot do

A key is a scoped analysis credential, not a login.

**It can:** run Starter and deep analyses, poll and enrich them, return structured `ideas-json` exports (schemaVersion 2), generate startup ideas, generate deep modules on your deep reports, and produce public share URLs when you pass `publish: true`.

**It cannot:** open the dashboard or read your account, change plans or billing or manage other keys, see personal analyses it did not create (reports you ran in the web app stay invisible to it), or rewrite your account preferences from a submitted founder profile.

**The one exception** is a key you gave Agency access. `agency:read` lists and exports every client report in your Consultant or Agency workspace, dashboard-created ones included, and `agency:write` spends that workspace's shared credits. Neither is ever granted implicitly, so a key that was not asked for them keeps the isolation above.

If a key leaks, revoke it. Your account itself is untouched.

## Common questions

### Is there a Preuve MCP server?
Yes. It is live with two transports and the same six tools (five for your own ideas, plus `get_agency` and a `workspace` switch for client work on a Consultant or Agency workspace), and listed in the Claude Connectors Directory (https://claude.ai/directory/preuve-ai). The remote server at https://mcp.preuve.ai/mcp works as a claude.ai connector (OAuth sign-in and a consent screen, no key handling) or with any HTTP MCP client sending an Authorization header. The original local stdio server remains fully supported.

### How do I get an API key?
Two ways. Connecting the Preuve connector from Claude signs you in and mints the key for you during consent, on any plan including free. Creating a key by hand at https://preuve.ai/app?settings=apiKeys is self-serve on a paid personal plan or in an active Consultant or Agency workspace. Start free: connect and run your first starter scans. Each key is scoped, sent in one `x-preuve-key` header, and tied to one Preuve account.

### What does the API return?
Polling returns run status, enrichment progress, per-module states, and URLs. The export endpoint returns structured `ideas-json` (schemaVersion 2): scores, verdict, market, competitors, SWOT, risks, quick take, and citations on every tier, plus the full deep report body on paid deep runs owned by your key.

### How much does it cost?
API usage draws from the same analysis quota as your Preuve plan. Starter scans come from your Starter allowance at no cost; deep scans come from your subscription, lifetime, or token balance. There is no separate API fee.

### Does a key give access to my dashboard?
No. A key cannot log in, read your account, change billing, or manage other keys. It sees only the analyses it created through the API, with one exception: a key carrying `agency:read` can also list and export every client report in your Consultant or Agency workspace, dashboard-created ones included, and `agency:write` can spend that workspace's shared credits. Those two scopes are never granted implicitly, so a key that was not asked for them has no such reach.

## Canonical

- HTML: https://preuve.ai/mcp
- Markdown: https://preuve.ai/mcp.md
- Developer docs: https://docs.preuve.ai/
- MCP server guide: https://docs.preuve.ai/mcp-server.md
- Agent behavior guide: https://docs.preuve.ai/for-ai-agents.md
- API key settings: https://preuve.ai/app?settings=apiKeys