Prospex docs

MCP

Connect an AI client to Prospex through the hosted URL or the local stdio bridge. Browser OAuth keeps credentials out of client settings.

The local bridge is the quickest setup. It signs you in through the browser, finds supported clients on this computer, and configures each one.

npx -y prospex mcp add

The installed entry runs npx -y prospex mcp serve. Credentials stay in the Prospex credentials file and never enter the client configuration. Use --dry-run to inspect the detected changes, or --client codex to configure one client.

Hosted connection

Cloud clients connect directly to the hosted transport. Enter this URL as the server address:

https://prospex.ch/mcp

The client opens Prospex for sign-in and consent. Dynamic registration, Authorization Code with S256 PKCE, token refresh, and revocation happen through OAuth. The client configuration contains the URL and no bearer key.

Client matrix

Client	Local bridge	Hosted OAuth	List builder app
Claude Code, including the desktop app	`mcp add` uses the native Claude command.	Add the hosted URL as an HTTP server.	Builds from the conversation.
Claude Desktop chat	`mcp add` updates the desktop MCP settings.	Use a custom connector with the hosted URL.	Shows the builder with the hosted connector.
Claude web connectors	Use the hosted transport.	Add the hosted URL as a custom connector.	Shows the builder in the conversation.
Codex	`mcp add` uses the native Codex command.	Add the hosted URL, then complete OAuth login.	Builds from the conversation.
Cursor	`mcp add` updates the global MCP settings.	Add the hosted URL as a remote server.	Builds from the conversation.

List builder app

Ask your assistant to build a list, for example "build me a list of Romandie industrial SMEs". It calls prospex_market_builder with what the conversation already settled. A client that supports MCP Apps opens a form in the conversation: you check the definition, add filters and example companies, start the build, and watch its four steps. The first ten companies appear when the build finishes, with a link to the full list on prospex.ch.

A client without MCP Apps support gets the same five tools. The assistant agrees the definition with you, saves it with prospex_save_market, starts the build with prospex_build_market, and polls prospex_market_status every 15 seconds. A build takes a few minutes.

The builder needs the markets:write scope and works on a free account with a confirmed email address: one built list, with its first ten companies visible. A refused save carries error.errors with one entry per field. A connection approved before this scope existed lacks it. Remove the connector and add it again, or run prospex login --scopes companies:read,markets:read,markets:write.

Authentication and scopes

Browser login requests companies:read, markets:read and markets:write. You can approve a connection that asks for a scope your plan does not cover yet. Tools behind that scope answer subscription_required until it does. Pilot customers can request entitled scopes with prospex login --scopes scope-a,scope-b. The approval page shows the client, scopes, resource, redirect host, and device code before access is granted.

A free account can use the company tools and read its own list here. Company rows then carry the register facts and the events the public company page shows, a list shows its first ten companies, and the budget is 20 companies a month. Each of those results carries a free_tier block with the subscription link. prospex_market_signals, the REST routes and the CLI need a subscription.

Access tokens last one hour. The CLI refreshes them before expiry and retries one request after an authentication failure. Refresh tokens last up to 90 days and rotate after every use. Revoke a connection under API keys and OAuth connections.

API keys remain available for CI and unattended automation. Put the key in PROSPEX_API_KEY so it stays out of command history and client settings.

Local and hosted transports

The local bridge reads newline-delimited JSON-RPC from stdin and sends it to the hosted MCP endpoint. It is useful for desktop clients that start stdio servers. Hosted OAuth connects an HTTP-capable client straight to Prospex and suits cloud connectors.

The tools

Tool	What it returns	Scope	Mode	Spends
prospex_usage	How many rows and requests this account has left today.	companies:read	read	nothing
prospex_search_companies	Search the Swiss commercial register.	companies:read	read	one row per company
prospex_get_company	One company, with its most recent events.	companies:read	read	one row per company
prospex_company_signals	What has happened at one company, newest first.	companies:read	read	one row per company
prospex_list_markets	Every list on this account: built lists, imported lists and followed companies.	markets:read	read	nothing
prospex_get_market	A list's origin, state, monitoring and, for a built list, its definition and queries.	markets:read	read	nothing
prospex_market_signals	Events on a list's companies, on the list's topics, newest first.	markets:read	read	one row per company
prospex_market_companies	One page of a list's ranking, with the reasons on each row.	markets:read	read	one row per company
prospex_market_builder	Open the list builder, to define a new list and build it.	markets:write	read	one row per company
prospex_save_market	Create a list, or change one, without building it.	markets:write	write	nothing
prospex_find_example_companies	Look a company up by name, to name it as an example for a list.	markets:write	read	nothing
prospex_build_market	Start building a saved list, or rebuild it after a change.	markets:write	write	nothing
prospex_market_status	How far a build has got, and the first companies once it is ready.	markets:write	read	one row per company
prospex_list_projects	The account's outreach projects, one per list.	prospect:read	read	nothing
prospex_list_prospects	The prospects in one outreach project.	prospect:read	read	one row per company
prospex_get_cycle	A cycle's current state and stage progress.	prospect:read	read	nothing
prospex_list_stage_jobs	The stage jobs an external outreach worker can claim.	prospect:stages	read	nothing
prospex_get_stage_job	A stage job with its immutable input and prior submissions.	prospect:stages	read	nothing
prospex_add_prospect	Resolve one company and attach it to an outreach project.	prospect:write	write	nothing
prospex_decide_prospect	Pin, exclude, restore, dismiss or set the language.	prospect:write	write	nothing
prospex_research_prospect	Request a fresh research cycle for one prospect.	prospect:run	write	nothing
prospex_approve_outreach	Approve one exact immutable outreach revision.	prospect:approve	write	nothing
prospex_start_cycle	Start the project now, or research named prospects.	prospect:run	write	nothing
prospex_claim_stage_job	Lease one external stage job to this credential.	prospect:stages	write	nothing
prospex_submit_stage_job	Submit output against a claimed job's input snapshot.	prospect:stages	write	nothing
prospex_fail_stage_job	Say why an external worker could not complete the job.	prospect:stages	write	nothing
prospex_cancel_stage_job	Cancel an external stage job.	prospect:stages	write	nothing
prospex_retry_stage_job	Open a fresh external job from the same immutable input.	prospect:stages	write	nothing
prospex_vocabulary	Every closed set a Prospex argument accepts.	companies:read	read	nothing

Each tool's schema declares additionalProperties: false, so an argument a model invents is refused with the accepted list rather than dropped. Enumerated values are generated from the same code the REST routes read, so prospex_vocabulary is always current.

Every tool publishes readOnlyHint, destructiveHint, idempotentHint and openWorldHint. A connection sees only the tools its scopes can call. Outreach write tools are available to pilot keys with the matching scope. They publish readOnlyHint: false and idempotentHint: true. An identical retry replays the first result. Pass idempotency_key when a workflow already has a stable retry key.

Caps

limit is held between 15 and 50, well below the REST routes' 100. A model pays for every token it reads back.
Every row is projected through the tool's own field list, so a result carries what the tool documents.
A result is cut at 8,192 bytes. count and truncated report what was dropped and has_more stays true, so the next call continues.
Row-spending tools spend the same row budget as company profiles, the feeds, the exports and the API: 250 a month on Starter, 1,000 on Pro and 10,000 on Business, with a daily ceiling of 125 a day on Starter, 500 on Pro and 5,000 on Business. A company read through the API and through MCP counts once a month. Every result carries a budget block with rows_left_today, rows_used_this_month, both limits and the seconds until each resets.

The protocol

JSON-RPC 2.0 over POST: initialize, notifications/initialized, ping, tools/list, tools/call, resources/list, resources/read.
Three resources, each served as text/html;profile=mcp-app under a ui:// URI that changes with each release: the list builder, a company card shown by prospex_get_company, and a company table shown by prospex_search_companies and prospex_market_companies. None loads anything from the network, and each declares an empty content security policy.
The hosted transport answers each POST with one JSON body. GET answers 405.
Revisions 2025-06-18, 2025-03-26. The initialize result echoes the negotiated version.
The server is stateless and does not issue an Mcp-Session-Id.
An authentication failure is HTTP 401 carrying WWW-Authenticate: Bearer with a resource_metadata pointer.
A refusal about your data, such as a missing list, an empty row budget, or an unavailable index, is a tool result with isError: true carrying error.code and, where it applies, retry_after. The model reads it and backs off.

Every response carries X-Request-Id. Quote it in a support message.

Troubleshooting

Run npx -y prospex whoami to see the active profile and remaining budget.
Run npx -y prospex mcp add --dry-run to see which local clients and settings Prospex detects.
Run npx -y prospex login again after a connection has expired or been revoked.
Keep MCP client logs on stderr. The stdio server reserves stdout for JSON-RPC messages.
Use the X-Request-Id from an error when contacting support.