> ## Documentation Index > Fetch the complete documentation index at: https://docs.preuve.ai/llms.txt > Use this file to discover all available pages before exploring further. # MCP Server > A viability score, competitors, and sources, in the chat you are already in. Score an idea without leaving Cursor, Claude, or Codex. Same analysis as [preuve.ai](https://preuve.ai): viability score, competitors, source-linked evidence. ```text theme={null} https://mcp.preuve.ai/mcp ``` Same key as [Get started](/). In claude.ai, Cursor, Claude Code, Codex and any other client with MCP OAuth, connecting signs you in and mints the key for you, which works on a free account. Start free: connect and run your first starter scans. A client that only takes a header needs one created by hand at [Account → API Keys](https://preuve.ai/app?settings=apiKeys), self-serve on a paid personal plan or in a Consultant or Agency workspace with an active subscription or a one-time unlock. A key made either way covers the five personal tools. [Agency client projects](#agency-client-projects) need two extra scopes that are never granted implicitly: tick **Include Agency workspace access** when creating the key by hand, or approve the Agency permissions on the consent screen when you sign in. ## Connect No key yet? In Cursor, claude.ai, Claude Code or Codex, use their tab instead, or add the server URL with no header in any other client with MCP OAuth: they sign you in, on a free account too. With a key, paste this as-is. Keep the key out of the chat. ```text theme={null} I want to validate startup ideas with Preuve: viability score, competitors, source-linked evidence. Add the Preuve MCP server. 1. I have a Preuve API key (prv_...) from https://preuve.ai/app?settings=apiKeys. Use it even where the client offers sign-in, so the scopes I chose carry over. Do NOT ask me to paste the key into chat. Put it in MCP config / env. 2. Add the remote server at https://mcp.preuve.ai/mcp (HTTP): - Claude Code: claude mcp add preuve --transport http https://mcp.preuve.ai/mcp \ --header "Authorization: Bearer " - Cursor: ~/.cursor/mcp.json: { "mcpServers": { "preuve": { "url": "https://mcp.preuve.ai/mcp", "headers": { "Authorization": "Bearer " } } } } - Claude Desktop config: { "mcpServers": { "preuve": { "url": "https://mcp.preuve.ai/mcp", "headers": { "Authorization": "Bearer " } } } } - Codex: export PREUVE_API_KEY= codex mcp add preuve --url https://mcp.preuve.ai/mcp \ --bearer-token-env-var PREUVE_API_KEY - Clients that only support stdio: npx -y mcp-remote https://mcp.preuve.ai/mcp \ --header "Authorization: Bearer " 3. Confirm the personal tools appear: start_analysis, get_analysis, enrich_analysis, export_analysis, generate_ideas. A sixth tool, get_agency, is listed for every account and is not an error. 4. First test with scanType "starter" only (it costs nothing): start_analysis on my idea, poll get_analysis, show me the viability score. Read https://docs.preuve.ai/agent-skill.md first. ``` ```bash theme={null} claude mcp add preuve --transport http https://mcp.preuve.ai/mcp ``` Then type `/mcp` in Claude Code, pick `preuve` and sign in with Preuve in the browser it opens. Approve, and Preuve creates a key for Claude Code, on any plan including free. No key to copy. Already have a key? Send it instead: ```bash theme={null} claude mcp add preuve --transport http https://mcp.preuve.ai/mcp \ --header "Authorization: Bearer $PREUVE_API_KEY" ``` Add this to `~/.cursor/mcp.json` (or the project `.cursor/mcp.json`): ```json theme={null} { "mcpServers": { "preuve": { "url": "https://mcp.preuve.ai/mcp" } } } ``` Cursor opens Preuve sign-in the first time it connects. Approve, and Preuve creates a key for Cursor, on any plan including free. No key to copy. Revoke it anytime from [API key settings](https://preuve.ai/app?settings=apiKeys). Already have a key? Send it instead, and Cursor skips the sign-in: ```json theme={null} { "mcpServers": { "preuve": { "url": "https://mcp.preuve.ai/mcp", "headers": { "Authorization": "Bearer prv_..." } } } } ``` ```bash theme={null} codex mcp add preuve --url https://mcp.preuve.ai/mcp codex mcp login preuve ``` The login opens Preuve sign-in in your browser. Approve, and Preuve creates a key for Codex, on any plan including free. Already have a key? Save it in `PREUVE_API_KEY`, then: ```bash theme={null} codex mcp add preuve \ --url https://mcp.preuve.ai/mcp \ --bearer-token-env-var PREUVE_API_KEY ``` In claude.ai (web or desktop): **Settings → Connectors → Add custom connector**. Paste: ```text theme={null} https://mcp.preuve.ai/mcp ``` Sign in with Preuve and approve. No key to copy. Preuve creates one for the connector. Revoke it anytime from [API key settings](https://preuve.ai/app?settings=apiKeys). If your client supports MCP OAuth, add `https://mcp.preuve.ai/mcp` with no header and sign in with Preuve, on a free account too. No key to copy. If your client cannot use a remote HTTP MCP server, bridge with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote): ```json theme={null} { "mcpServers": { "preuve": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.preuve.ai/mcp", "--header", "Authorization: Bearer prv_..." ] } } } ``` If you have this repo, you can run the local server instead: ```bash theme={null} claude mcp add preuve \ --env PREUVE_API_KEY=$PREUVE_API_KEY \ -- node /path/to/scripts/preuve-mcp-server.mjs ``` ## Tools | Tool | What it does | | - | - | | `start_analysis` | Start one scan. You must pass `scanType`: `starter` (free) or `deep` (paid). A **personal** deep scan also requires `stage` and `budget`; an Agency client project does not. To screen several ideas, call it once per idea. Optional `workspace`. | | `get_analysis` | Check status, progress, and report URLs. Does not return the result itself. Takes a run id or a report id, and resolves **any personal starter or deep report the account owns**, including ones created on the preuve.ai dashboard. A dashboard one comes back with `exportable: false`. Optional `workspace`. | | `enrich_analysis` | Fill in missing sections. Safe to call twice. Can start extra modules on a deep scan. Like the export, it serves analyses this API started: a dashboard report is refused with `403 REPORT_NOT_FROM_AGENT_RUN`. | | `export_analysis` | Get the JSON result for one completed scan **this API started**. A report created on the dashboard is refused with `403 REPORT_NOT_FROM_AGENT_RUN`; the refusal text names the way forward for that report, which may be Build with AI on its report page or unlocking it there, and running the idea again here with `start_analysis` always works. Optional `verbosity` and `workspace`. There is no `format` parameter: the export is always the same JSON shape. | | `generate_ideas` | Generate startup ideas from interests. Free accounts: 5 per rolling 24 hours. `pro` is a paid perk; founder-profile tailoring is automatic on paid accounts with a saved profile. Spends no scan quota. | | `get_agency` | Read a Consultant or Agency workspace in one call: role, remaining shared project credits, and the client reports already in it, newest first with `nextOffset` for paging. See [Agency client projects](#agency-client-projects). | On a few fields the MCP schema is stricter than the HTTP API, and it validates before the call rather than trimming after it. `idea` must be 40 to 50,000 characters, `targetMarket` at most 180, and `targetCountry`, `stage` and `budget` at most 80. One schema serves both workspaces, so it carries the Agency route's bounds even on a personal scan, where the HTTP route would have accepted a longer value and trimmed it. Size to these limits if you send the same body both ways. ### Agency client projects Consultant and AppSumo Agency accounts reach their workspace through the same tools: `get_agency` reads the workspace, and `workspace: "agency"` on `start_analysis`, `get_analysis` and `export_analysis` acts on it instead of the account's own ideas. These use the same project quota as the Agency dashboard, and they need TWO things, checked in that order: a key carrying the scope that call needs, then live workspace membership. The two Agency scopes are enforced per route and neither implies the other, so a key holding only `agency:read` cannot start a client project and one holding only `agency:write` cannot read the workspace, poll or export a report (see the Scope column below). A key without the scope gets `403 INSUFFICIENT_SCOPE` and never reaches the membership check, which is what every key created before 2026-09-09 receives; a scoped key on an account belonging to no workspace gets `404 AGENCY_NOT_FOUND`. Personal AppSumo Tiers 1-3 continue to use the personal tools above. `enrich_analysis` takes no `workspace`, and client reports never need it: an Agency report is exportable the moment its status is `COMPLETED`. Calling `enrich_analysis` with a client `reportId` reaches the personal route and returns `404`. A client project is always deep, and the `stage` and `budget` rule does not follow it there. Both stay optional, and both take free text up to 80 characters rather than the personal vocabulary, because a consultant records what the client said. Send them only as the client stated them, and start the project without them otherwise. All six tools are advertised to every client, with no scope filter. That is deliberate: a personal-only key discovers the Agency door and gets a refusal naming the recovery, instead of "unknown tool" from a list that changed shape between two accounts. The consequence is that a client which keeps making an Agency call on a key without the scope gets `403` every time, indefinitely. Nothing self-heals: the refusal is an answer, not a failure, and it ends when the key is replaced. One ceiling still applies, and it is not a scope ceiling. Every authenticated request passes an attempt limiter that bounds the key lookup itself, so a client looping hard enough to exhaust it receives `429 RATE_LIMITED` instead of the `403`, and the actionable message with it. Waiting clears the `429` and returns the `403`; only a new key clears the `403`. | Call | Scope | What it does | | - | - | - | | `get_agency` | `agency:read` | Your workspace, role, remaining project quota, and the client reports list, dashboard-created ones included. | | `start_analysis` + `workspace: "agency"` | `agency:write` | Create a deep client report using one shared Agency project credit. | | `get_analysis` + `workspace: "agency"` | `agency:read` | Check a client report's status. | | `export_analysis` + `workspace: "agency"` | `agency:read` | Read a completed client report as JSON, with `full` or `summary` verbosity. | Ask your agent: "Check my Agency quota, then run a deep client project for this idea." Starting a project spends Agency quota and never falls back to personal credits. Reuse the same `clientRunId` after a timeout to recover the original report without starting or charging for another one. An uncertain dispatch returns `dispatchPending: true`; retry the same start with the same `clientRunId` after 60 seconds. Recovery uses the original report and credit. After 23 hours, the response directs you to support instead of risking a duplicate job. A definite dispatch rejection restores the credit and returns `TRIGGER_DISPATCH_FAILED`. That failed request stays failed on replay; use a new `clientRunId` only when you intentionally start a new attempt. One `clientRunId` namespace covers both workspaces on a key. An id that already started a client project cannot start a personal scan, or the reverse: it returns `409 CLIENT_RUN_ID_CONFLICT`. Changing `workspace` on a start you have already sent needs a new id. Reports appear in the Agency dashboard. Creating one through MCP does not email the client or publish a share link. Existing client reports can be read without having been created through MCP. Removing a collaborator's workspace membership removes their Agency access on the next call, even if their personal key remains valid. Starter and refunded reports retain their normal content restrictions. Client sharing, pivots and other dashboard actions remain in the dashboard. ### Keeping exports small `export_analysis` takes `verbosity`: `full` or `summary`. `summary` keeps every scored field: score, verdict (including the Bottom Line narrative under `details.verdict.narrative`), competitors, market size, risks and pivots. One subsection survives the trim: `details.sections.synthesis`, the report's closing verdict (final verdict, key strengths and weaknesses, deal breakers, pivot recommendation). Every summary drops the other section prose but keeps their numbers and short values, and counts Google Trends data points. Everything else stays whole when it fits. On the largest reports the summary then reduces raw evidence and how-to material (forum posts, prospects, the playbook, action plans, sources, citations) to numbers and short text, and cuts the remaining long text to the largest length that fits one tool result (65,000 JSON characters). Numbers, short values, each verdict and the closing verdict are never cut. What it changed is listed under `details.omitted`. `export_analysis` defaults to `full`, in both workspaces. ### Locked fields on a starter scan A starter scan returns a real analysis, not a partial one, but it leaves the deep-tier fields null. A deep scan on the same idea fills in `details.sections` and `details.pivots` directly. Five more, `details.founderFit`, `details.playbook`, `details.googleTrends`, `details.proofOfDemand` and `details.communityDemand`, are opt-in modules: a deep report makes them available, and `enrich_analysis` generates them on request. Competitor detail, risk explanations, market segmentation (`details.market.segments`, `industryTrends`, `competitivePositioning`) and source citations (`details.citations`, `details.searchContext.sources`) are withheld the same way the web report withholds them from a free viewer. When anything is withheld, the export carries a top-level `locked` object naming each field, what unlocks it, and why. Read it before concluding a field is missing: `null` there means locked by tier, not a failed analysis. ## Slash commands The server also exposes two MCP prompts. They are shortcuts for you, not tools the model calls: pick one from your client (in Claude Code they are `/mcp__preuve__validate_idea` and `/mcp__preuve__generate_ideas`; in claude.ai they are under the **+** menu, Connectors). * `validate_idea`, taking the idea as its only argument, drops in a request that runs the scan and polls it to completion. * `generate_ideas`, taking your interests as its only argument, drops in a request that generates startup ideas - no prior report needed. ## Example prompts ```text theme={null} Validate this idea with a starter scan: "AI bookkeeping for solo lawyers in France" Run a deep scan on my top idea, then generate the launch playbook and proof of demand once it completes. Score these 4 ideas with starter scans and rank them by viability score. ``` A deep scan spends the same quota as the web app. The MCP server does not add a second bill. See [Quotas and billing](/quotas-and-billing). ## Teach your agent the workflow Your agent can keep scoring ideas without burning a paid scan. The [Agent Skill](/agent-skill) is that judgment: starter vs deep, when to wait, when a retry is safe. Without it, agents often retry with a new id and spend a second deep scan. Install it once. It is a markdown file, not another key. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.