---
title: "Startup validation API and MCP server for AI agents"
slug: mcp
description: "Validate startup ideas from any AI agent. Remote MCP server at mcp.preuve.ai for claude.ai connectors, Claude Code, and Cursor, plus an API-key HTTP API - live in early access."
canonical: https://preuve.ai/mcp
---

# Preuve MCP server and Agent API

Score a startup idea from your agent: viability score, competitors, market sizing, demand signals, every claim source-linked. Seven MCP tools. 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).

**Claude Code, Cursor, Codex, or any HTTP MCP client.** Get a key at https://preuve.ai/app?settings=apiKeys (self-serve, paid Preuve account required), then:

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

**claude.ai, web or desktop.** Add a custom connector pointing at `https://mcp.preuve.ai/mcp`. Sign-in and consent happen in the browser and the key is issued automatically, so there is nothing to copy. Revoke it 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. Seven `preuve` tools should appear. 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 eight minutes.

Early access beta. The tool and endpoint contracts and the error codes are stable; rough edges are possible.

## 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. |
| `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. |
| `create_batch` | Up to 10 runs in one batch, idempotent on the batch `clientRunId`. |
| `get_batch` | Per-item statuses for a batch. |
| `export_batch` | Batch export with `counts.exported/omitted` and per-item omission reasons. |

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 10 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 |

### 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" }
  },
  "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 10 ideas.
- `batch:read` - poll batch status and child run URLs.
- `export:read` - export completed analyses and batches as JSON.

## 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. Beta: results can be uneven, every quote links to its source.
- `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.

## 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 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 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.

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 seven tools. The remote server at https://mcp.preuve.ai/mcp works as a claude.ai custom 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?
Keys are self-serve for paid Preuve accounts. Generate one instantly at https://preuve.ai/app?settings=apiKeys. 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 only sees analyses it created through the API.

## 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