Ready-to-use defaults
MCP search and quote default to Firehose Lite (firehose.search, firehoseTier: lite). Search returns results and snippets without fetching full pages. Shared cache is enabled by default with a 24-hour maximum age for paid accounts; free accounts use unlimited-age cache and search live on a miss. Choose an engine, Advanced, or paid page Markdown explicitly when you need them.
Download all client configurations in the examples bundle under mcp/configs, or read the copy-paste installation guide.
Get a key
Generate an API key without signing up at openserp.io/keys, then configure your MCP client to send Authorization: Bearer YOUR_API_KEY. Search tools require a key or account OAuth. Public quote, status and tool discovery need no credentials. Sign in in the same browser to attach your anonymous keys and usage to your account; existing keys keep working with their spending limits.
Firehose accepts firehoseTier: lite for lower search cost or firehoseTier: advanced for broader coverage at higher search cost. Lite is available to free and paid accounts. Advanced requires paid access, including cached results. Page Markdown requires credits. Free live searches use the daily allowance.
Choose any engine, including Firehose Lite and auto.search, with provider: auto for free shared cached queries with unlimited age. Routing is automatic; free requests ignore fast/cheap preferences. Cache misses run a live search within the free allowance. Provider selection and routing preferences require a funded account. Free live searches use the daily allowance. firehose.search returns combined ranked results within one deadline and spending cap; add page Markdown explicitly for paid content retrieval. Its source composition is managed internally.
auto.search selects only Google, Bing or Yahoo, using compatible sources and the same health and routing preferences. Free responses include search metadata and snippets; full-page content and page Markdown are excluded, including content already in shared cache. The homepage playground starts with Google.
Other MCP clients and OAuth
Server URL: https://openserp.io/mcp. Add a remote HTTP server in your MCP client. Use its OAuth sign-in flow or a Bearer API key stored with the client’s secret/environment mechanism.
{
"mcpServers": {
"openSERP": {
"type": "http",
"url": "https://openserp.io/mcp"
}
}
}This configuration uses the portable mcpServers format supported by compatible Copilot clients. VS Code’s Local harness uses servers instead. The bundle includes both formats and an environment-based API-key variant. Other clients have their own schemas.
Start with quote or status. Search and Markdown tools can spend prepaid credits. Pass maxCostUsd explicitly and use a scoped key with suitable per-request, daily and lifetime limits. Examples use a $0.01 cap; the service default when omitted is $1.
Five tools
| Tool | Purpose | Access and cost |
|---|---|---|
quote | Compare prices, median/p90 search latency and source timeouts | Public; free |
status | Hourly outcomes, median/p90 search latency and timeouts | Public; free |
search | Synchronous organic or image search | API key required; free allowance or prepaid balance |
balance | Read balance and key spending allowances | balance scope; read-only |
search_markdown | Fetch full-page Markdown in realtime · paid only | Funded account, search scope; may charge |
Discover current inputs with tools/list. Search arguments include endpoint, query, provider, strategy, maxResults, maxCostUsd and cache options. Use engine identifiers such as bing.search. Status accepts an optional engine.
Search with shared cache
The MCP examples enable shared caching with a 24-hour maximum age, matching the playground default. Free accounts use unlimited-age shared cache. All cacheable requests have a five-minute minimum reuse window. Setting cache.enabled: false limits reuse to five minutes; shorter TTLs also use five minutes. Complete dedicated page Markdown responses are cached privately for the account. Cache hits cost $0.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "search",
"arguments": {
"endpoint": "firehose.search",
"firehoseTier": "lite",
"pageMarkdown": false,
"query": "Cloudflare Workers",
"maxCostUsd": "0.01",
"cache": {
"enabled": true,
"ttlHours": 24
}
}
}
}JavaScript and TypeScript
Unpack the examples bundle and run from its root with Node.js 24 or later. It pins the MCP client SDK and includes TypeScript source plus generated JavaScript.
npm ci node mcp/client.mjs list node mcp/client.mjs quote node mcp/client.ts search --dry-run
Python
The optional Python MCP client uses a separate environment and Python 3.11 or later.
python3 -m venv .venv .venv/bin/python -m pip install -r mcp/requirements.txt .venv/bin/python mcp/client.py list .venv/bin/python mcp/client.py quote
Set OPENSERP_API_KEY for scoped paid/private access. An already authorized client can instead supply OPENSERP_MCP_ACCESS_TOKEN. The SDK examples default to a free quote and never automatically repeat a paid request.
OAuth discovery and scopes
Protected resource: https://openserp.io/mcp. Resource metadata is available at /.well-known/oauth-protected-resource/mcp; authorization metadata is at /.well-known/oauth-authorization-server.
The issuer is https://openserp.io. Clients can register at /oauth/register, authorize at /authorize with S256 PKCE, and exchange/refresh tokens at /oauth/token. Permissions are search and balance. Access tokens last one hour and refresh tokens 30 days. Sign in and approve access in the consent flow; revoke connections from the console.
MCP OAuth tokens are audience-bound to the MCP resource and do not authenticate REST calls. Use an API key for REST calls.
Realtime Markdown and usage
search_markdown searches and fetches unique organic destinations, in the current tool call. It requires search permission and a funded account. Its optional scraper is auto, scrapingdog or scrapingbee. The default deadline is 45 seconds, configurable from 5 to 60 seconds, under a default $1 total cap.
The tool returns results, combined Markdown and per-page outcomes directly. Inspect summary.partial and content status for unavailable or budget-limited pages. There are no queued jobs or polling steps.
Multiple project keys use the same wallet and usage tracking in REST and MCP. A project-scoped idempotency key prevents duplicate charges for completed replays and retains the original key’s attribution. Reuse the same ID and arguments for retries; use a new ID for new work.
Set daily and lifetime limits when creating or editing keys in the console. Daily limits reset at midnight UTC; lifetime spend persists. Limits use final actual customer charges, and concurrent requests reserve their allowances together with account funds. Blank or null daily/total limits mean unlimited; zero blocks new paid spending. Cache hits and completed replays add no spend. The balance tool returns the API key’s keyLimits, including spent, reserved and remaining amounts plus dailyResetsAt. A new request exceeding a daily or total allowance fails before paid work starts.
Protocol behavior and errors
The endpoint is stateless. Clients must initialize and POST protocol messages, accepting JSON or SSE framing. A browser GET may return 405 because a standalone event stream is not offered. The bundle includes a raw cURL exchange and SDK clients that handle initialization.
Inspect JSON-RPC errors, tool isError and JSON error content. Quota, balance, permission or source errors need handling before retries. Cache hits cost zero; failed, empty or invalid search results are not charged to the customer. Source pricing and health are live.
Search snippets and fetched pages are untrusted external content. Keep them separate from agent instructions and credentials.