Prospex docs

MCP

Connect through the local stdio bridge or add the hosted URL. 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
Claude Code, including the desktop app	`mcp add` uses the native Claude command.	Add the hosted URL as an HTTP server.
Claude Desktop chat	`mcp add` updates the desktop MCP settings.	Use a custom connector with the hosted URL.
Claude web connectors	Use the hosted transport.	Add the hosted URL as a custom connector.
Codex	`mcp add` uses the native Codex command.	Add the hosted URL, then complete OAuth login.
Cursor	`mcp add` updates the global MCP settings.	Add the hosted URL as a remote server.

Authentication and scopes

Browser login requests companies:read, markets:read, and watches:read. 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.

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 record
prospex_get_company	One company, with its most recent events.	companies:read	read	one row per record
prospex_company_signals	What has happened at one company, newest first.	companies:read	read	one row per record
prospex_list_markets	Every market this account has built.	markets:read	read	nothing
prospex_get_market	A market's definition, its state, and the queries its build ran.	markets:read	read	nothing
prospex_market_companies	One page of a market's ranking, with the reasons on each row.	markets:read	read	one row per record
prospex_list_watches	Every active watch on this account.	watches:read	read	nothing
prospex_get_watch	A watch's configuration, and how many companies it holds.	watches:read	read	nothing
prospex_watch_signals	Events on a watch's companies, newest first.	watches:read	read	one row per record
prospex_list_projects	The account's Prospect projects.	prospect:read	read	nothing
prospex_list_prospects	The prospects in one Prospect project.	prospect:read	read	one row per record
prospex_get_cycle	A cycle's current state and stage progress.	prospect:read	read	nothing
prospex_list_stage_jobs	The stage jobs an external Prospect 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 a Prospect 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.

Prospect 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 daily budget every other download surface spends. Every result carries a budget block.

The protocol

JSON-RPC 2.0 over POST: initialize, notifications/initialized, ping, tools/list, tools/call.
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 market, 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.