MCP reference
The MCP endpoint, the two ways to sign in, and every MCP tool with its input, a real result captured from staging, and when an agent should use it.
The endpoint
https://api.parel.si/mcp
Streamable HTTP, stateless (one server per request, no session id), JSON responses. The server advertises tools with listChanged. Captured from staging, the initialize result:
{
"result": {
"protocolVersion": "2025-06-18",
"capabilities": {
"tools": {
"listChanged": true
}
},
"serverInfo": {
"name": "Parel",
"version": "0.0.1"
}
},
"jsonrpc": "2.0",
"id": 1
}
Two ways to sign in
| Client | Credential | What happens |
|---|---|---|
| claude.ai, Claude Desktop | Sign in with your Parel account ("Sign in now", "Register automatically") | The 401 from /mcp carries WWW-Authenticate: Bearer resource_metadata="…"; Claude reads the metadata at https://api.parel.si/.well-known/oauth-protected-resource, registers itself with the sign-in server and sends you to a Parel page to approve. The token resolves to a hidden "Claude connector" key on your team. |
| Claude Code, Cursor, Codex, n8n, any MCP client | Authorization: Bearer sk_… | The API-key path, exactly as on /v1. |
Both end on the same code path: scopes, caps, holds, the rate limit and the usage log are the key's. Details and every failure: Authentication. The per-key rate limit (300 paid calls per minute) and the run scope are enforced inside run_tool and the headline tools; the free tools need only a valid credential.
How results come back
Every tool result is one text content block holding JSON. A failure has isError: true and the same body as the REST error, plus request_id; confirmation_required is the one exception, returned without isError because it is a quote the agent should show the user. A result over 48,000 characters is cut to whole list items with a _truncated note (Limits).
The tool list, captured from staging before 2026-11-17 (descriptions shortened; input lists each tool's arguments). Since then discover_tools also takes job, and its description is the one under discover_tools below:
{
"result": {
"tools": [
{
"name": "discover_tools",
"description": "Free. List the paid data tools available (web search, email finding, SEO, AI visibility, social data), headline tools first, each with a one-line summary, today…",
"input": [
"query"
]
},
{
"name": "inspect_tool",
"description": "Free. Everything about one tool before you run it: the full description, notes (quirks, rate limits, response size), input_schema (required fields, one-of sets,…",
"input": [
"tool"
]
},
{
"name": "run_tool",
"description": "Run a tool by name with its input. Paid per call from the prepaid rupee balance; failed calls cost ₹0, and so do empty results except on a tool whose description says it charges every lookup. Returns the result plus cost_paise and …",
"input": [
"tool",
"input",
"idempotency_key",
"client_tag"
]
},
{
"name": "quote_tool",
"description": "Free. Estimate what a call would cost before running it: the likely charge and the amount held, in paise, for this exact input, plus whether the balance covers …",
"input": [
"tool",
"input"
]
},
{
"name": "get_run",
"description": "Free. Check the status and cost of a previous call by its call_id (also used for slow research jobs).",
"input": [
"call_id"
]
},
{
"name": "check_balance",
"description": "Free. Show the prepaid balance in rupees and where to top up.",
"input": []
},
{
"name": "check_ai_visibility",
"description": "What ChatGPT answers to a prompt right now, from a country: text, sources, brands cited. What ChatGPT answers to a prompt right now, from a chosen country: the …",
"input": [
"state",
"legacy",
"prompt",
"country",
"include",
"disableWebSearch"
]
},
{
"name": "find_email",
"description": "One person's work email from name + company domain, with confidence; a miss is free. One person's work email from their name and company: give domain (preferred…",
"input": [
"domain",
"company",
"full_name",
"last_name",
"first_name",
"max_duration",
"linkedin_handle"
]
},
{
"name": "get_social_posts",
"description": "A public Instagram account's recent posts with captions, media and engagement counts. A public Instagram account's recent posts from its handle: for each post t…",
"input": [
"handle",
"next_max_id"
]
},
{
"name": "search_web",
"description": "Google organic results for a query, by country and language. Google organic results for a query as structured rows (position, title, link, snippet) for a chosen…",
"input": [
"q",
"limit",
"country",
"language",
"ai_overview"
]
}
]
},
"jsonrpc": "2.0",
"id": 2
}
Free tools
discover_tools
Find the right tool for a task. Use it first when unsure which tool fits, saying what you need in a few words: "work email of a person", "competitor ads", "who is hiring", "Instagram posts of a brand". The words are matched one by one and ranked (how, in POST /v1/discover), so their order does not matter.
| Argument | Type | Required | Description |
|---|---|---|---|
query | string | no | What you need, in a few words. Leave it out for the list of jobs |
job | string | no | A job id from the no-query answer (work_email, instagram): every tool of that job; with query, the best of that job |
With a query: at most eight tools, best first, each with its summary, today's estimated cost, whether it needs confirmation, headline, its job and, on look-alike tools, pick_when (when to pick this one over its siblings). A verdict says how well they fit:
match: the first tool fits. The first three rows also carrydescription,input_schemaandhow_to_run, so the first one can usually be run withoutinspect_tool.nearest: only something close was found; ahintsays how to ask differently. Check before running.none: nothing fits;toolsis empty, ahintsays how to describe the task differently, andjobslists the jobs to browse instead.
Computed in-process from the seeded catalogue on 2026-11-17 with query: "work email of a person" (three rows shown, descriptions and the later schemas shortened):
{
"query": "work email of a person",
"verdict": "match",
"tools": [
{
"name": "find_email",
"summary": "One person's work email from name + company domain, with confidence; a miss is free.",
"price": "~₹2.77 per successful result; a miss is free",
"estimated_cost_paise": 277,
"estimated_cost": "₹2.77",
"async": false,
"free_when_no_result": true,
"confirm_required": false,
"headline": true,
"job": "work_email",
"pick_when": "One known person at one company. Everyone at a company: domain_search; the format only: get_email_pattern.",
"description": "One person's work email from their name and company: give domain (preferred) or company, plus full_name or first_name and last_name; or linkedin_handle alone. Returns the best-guess address with a confidence score (0 to…",
"how_to_run": "Call the find_email tool directly.",
"input_schema": {
"type": "object",
"properties": {
"domain": {
"type": "string",
"description": "the company's domain — preferred over company. e.g. \"reddit.com\""
},
"company": {
"type": "string",
"description": "company name, when you don't know the domain"
},
"linkedin_handle": {
"type": "string",
"description": "identifies EITHER the person or the company — it can stand in for the name pair or for domain/company"
},
"first_name": {
"type": "string",
"description": "use with last_name. e.g. \"Alexis\""
},
"last_name": {
"type": "string",
"description": "e.g. \"Ohanian\""
},
"full_name": {
"type": "string",
"description": "alternative to first_name + last_name"
},
"max_duration": {
"type": "integer"
}
},
"description": "one of domain | company | linkedin_handle, plus either full_name or first_name + last_name (or linkedin_handle alone). The response carries a confidence score, the sources the address was seen on, and an automatic verification of the address it found",
"anyOf": [
{
"required": [
"domain",
"full_name"
]
},
{
"required": [
"domain",
"first_name",
"last_name"
]
},
{
"required": [
"company",
"full_name"
]
},
{
"required": [
"company",
"first_name",
"last_name"
]
},
{
"required": [
"linkedin_handle"
]
}
]
}
},
{
"name": "enrich_person",
"summary": "One known person from a work email, LinkedIn URL or name and company: title, employer, seniority, location, career history.",
"price": "~₹2.94 per successful result; a miss is free",
"estimated_cost_paise": 294,
"estimated_cost": "₹2.94",
"async": false,
"free_when_no_result": true,
"confirm_required": false,
"headline": false,
"job": "person_profile",
"pick_when": "One known person from an email, profile link or name and company; LinkedIn's own profile: get_linkedin_profile.",
"description": "One known person from a linkedin_url, a work email, or a name with an employer: data.person with name, title, headline, seniority, functions, city and country, employment_history[] and organization (name, domain, indust…",
"how_to_run": "Call run_tool with tool: \"enrich_person\" and input matching input_schema.",
"input_schema": {
"…": "shortened here"
}
},
{
"name": "get_email_pattern",
"summary": "The email address formats a company uses (first.last, flast…) and how common each is, from its domain.",
"price": "~₹0.25 per successful result; a miss is free",
"estimated_cost_paise": 25,
"estimated_cost": "₹0.25",
"async": false,
"free_when_no_result": true,
"confirm_required": false,
"headline": false,
"job": "work_email",
"pick_when": "The format a company uses, not an address; to get one person's address use find_email.",
"description": "The address formats a company's email follows, from its domain: data with the patterns (first.last, first, flast and so on), each with its share and, with emailsCount true, how many known addresses back it. Use it to bu…",
"how_to_run": "Call run_tool with tool: \"get_email_pattern\" and input matching input_schema.",
"input_schema": {
"…": "shortened here"
}
}
],
"note": "Best first. The first 3 carry input_schema and how_to_run; call inspect_tool for any other. pick_when says which of two look-alike tools fits."
}
And with query: "book a cab to the airport", which Parel has no tool for (two rows shown):
{
"query": "book a cab to the airport",
"verdict": "nearest",
"tools": [
{
"name": "search_flights",
"summary": "Google Flights options for a route and date: airlines, times, stops, duration and price, with the typical price range for the route.",
"price": "~₹1.70 per successful result; a miss is free",
"estimated_cost_paise": 170,
"estimated_cost": "₹1.70",
"async": false,
"free_when_no_result": true,
"confirm_required": false,
"headline": false,
"job": "travel_weather"
},
{
"name": "get_airbnb_listing",
"summary": "One Airbnb listing by its link or id: type of place, city, guests, bedrooms, beds, rating, review count, description and photos.",
"price": "~₹0.25 per successful result; a miss is free",
"estimated_cost_paise": 25,
"estimated_cost": "₹0.25",
"async": false,
"free_when_no_result": true,
"confirm_required": false,
"headline": false,
"job": "travel_weather"
}
],
"hint": "No tool fits every part of this; these are the closest. If none of them fits, describe the task differently, or list one job's tools with job (the job ids are in discover_tools with no keyword)."
}
With no query: the jobs Parel covers, each with its job id, label, how many tools and up to three examples, plus tool_count and a note. This answer stays under 5,000 characters however many tools there are; until 2026-11-17 it was every tool, about 30,000 characters. The first six jobs shown:
{
"tool_count": 191,
"note": "191 tools in 35 jobs. Call discover_tools with a few words for what you need (\"work email of a person\", \"competitor ads\", \"who is hiring\") to get the best tools first, or with job (an id below) for every tool of one job. Headline tools can be called directly: search_web, find_email, get_social_posts, check_ai_visibility.",
"jobs": [
{
"job": "web_search",
"label": "Web search: Google, Bing, deep",
"tools": 6,
"examples": [
"search_web",
"search_semantic",
"search_deep"
]
},
{
"job": "research_reference",
"label": "Cited answers, papers, patents",
"tools": 6,
"examples": [
"answer_question",
"search_podcasts",
"search_scholar"
]
},
{
"job": "news_feeds",
"label": "News, blogs and feeds",
"tools": 7,
"examples": [
"search_news",
"search_hacker_news",
"get_product_hunt_launches"
]
},
{
"job": "read_websites",
"label": "Read, crawl or extract web pages",
"tools": 7,
"examples": [
"read_page",
"read_pages",
"extract_page"
]
},
{
"job": "maps_places",
"label": "Places and reviews on Maps",
"tools": 4,
"examples": [
"search_maps",
"get_maps_reviews",
"search_local"
]
},
{
"job": "travel_weather",
"label": "Hotels, flights and weather",
"tools": 4,
"examples": [
"search_hotels",
"get_weather",
"search_flights"
]
}
]
}
With job: every tool of that job, headline tools first, each with its description and how_to_run; inspect_tool gives the schema. An unknown job answers error: "unknown_job" with the list of jobs.
inspect_tool
Everything about one tool before you run it: description, notes, input_schema, one_of sets, example_input, today's price and hold_paise, timeout_seconds, how_to_run, whether it needs confirm: true. Never guess a tool's input; inspect it. The same view as GET /v1/tools/:id.
| Argument | Type | Required | Description |
|---|---|---|---|
tool | string | yes | A name from discover_tools |
Captured for get_reddit (description shortened):
{
"name": "get_reddit",
"summary": "Posts from one subreddit: title, score, comments count, text; hot, new, top or rising.",
"description": "Posts from one subreddit by name (without r/): title, author, score, comment count, flair, created time, link and post text, sorted hot (default), new, top or rising. Use it to read what a community is discussing. It does not search across Reddit, does not return a post's comments, and cannot read p…",
"price": "~₹0.28 per call",
"estimated_cost_paise": 28,
"estimated_cost": "₹0.28",
"async": false,
"free_when_no_result": true,
"confirm_required": false,
"notes": [
"About 25 posts per call, around 30 KB.",
"sort: hot, new, top, rising.",
"… 1 more"
],
"input_schema": {
"type": "object",
"required": [
"subreddit"
],
"properties": {
"sort": {
"type": "string",
"description": "Sort order"
},
"subreddit": {
"type": "string",
"description": "Subreddit name. e.g. \"news\""
}
}
},
"one_of": null,
"example_input": {
"sort": "hot",
"subreddit": "IndiaInvestments"
},
"hold_paise": 42,
"timeout_seconds": 30,
"how_to_run": "Call run_tool with tool: \"get_reddit\" and input matching input_schema.",
"quote": "Call quote_tool with this tool and your input to see the estimated charge and the hold before running it."
}
quote_tool
The estimated charge and the hold for an input, in paise, and whether the balance covers it. Free; nothing is recorded. Use it before any call the user may think expensive, before a loop, and always when a tool says it needs confirmation. The same numbers as POST /v1/quote.
| Argument | Type | Required | Description |
|---|---|---|---|
tool | string | yes | |
input | object | no | The input you intend to send |
Captured:
{
"ok": true,
"tool": "find_email",
"quote": true,
"charged_paise": 0,
"estimate_paise": 280,
"estimate": "₹2.80",
"hold_paise": 420,
"hold": "₹4.20",
"confirm_required": false,
"free_when_no_result": true,
"async": false,
"balance_paise": 9850,
"enough_balance": true,
"note": "Estimate at today's rate: what this call normally costs. A failed call costs nothing. The real charge follows what the source bills; if that is more than the hold, the extra is taken only when your balance covers it, and a balance never goes below zero. Nothing was charged for this quote."
}
get_run
The status and cost of a previous call by its call_id; for a slow job, the poll that finishes it. Use it when your side lost an answer before running the call again, and to poll a 202. The same read as GET /v1/runs/:id.
| Argument | Type | Required | Description |
|---|---|---|---|
call_id | string | yes |
Captured for a call that failed upstream (₹0):
{
"call_id": "ff83d554-fb75-4cf9-896a-bf53f91ea587",
"tool": "search_web",
"class": "upstream_error",
"cost_paise": 0,
"error": "upstream_error",
"finished_at": "2026-10-27T20:36:21.744Z"
}
check_balance
The prepaid balance in rupees and paise, topup_url, and how_to_get_credit, the sentence to show the user when they need more credit. Use it to verify a new connection and after insufficient_balance.
{
"result": {
"content": [
{
"type": "text",
"text": "{\"balance\":\"₹98.50\",\"balance_paise\":9850,\"topup_url\":\"https://app.parel.si/topup\",\"how_to_get_credit\":\"During the beta, credit is added by Parel on request: email hello@parel.si with the team name. Nothing is charged for failed calls.\"}"
}
]
},
"jsonrpc": "2.0",
"id": 3
}
Paid tools
run_tool
Run any tool by name. Scope run; counts against the rate limit. Returns the same body as POST /v1/run: data plus cost_paise and balance_paise, or an error with charged_paise: 0.
| Argument | Type | Required | Description |
|---|---|---|---|
tool | string | yes | A name from discover_tools |
input | object | no | The tool's input. confirm: true inside it runs a call that needs the user's approval, once they have approved the quoted cost. |
idempotency_key | string | no | A repeat of a call with the same key is never charged twice: an answer already received comes back for ₹0, one not yet received is charged once. A different tool or input takes a new key |
client_tag | string | no | A label for spend tracking in the dashboard |
Captured, an input that failed validation (₹0, the source never called):
{
"ok": false,
"call_id": "1c42172a-4eed-4bd9-bad4-9a4c89495024",
"error": "invalid_input",
"message": "Input did not match the tool's schema.",
"charged_paise": 0,
"retryable": false,
"errors": [
{
"path": "$.subreddit",
"message": "is required"
}
],
"request_id": "9cf8c889-c35c-4292-94fc-d5ebbe3bf71f"
}
Captured, a call the source refused (₹0, isError: true; on 2026-10-28 the staging environment's connection to the source was being re-keyed, so every paid call failed this way):
{
"ok": false,
"call_id": "ccc9ade4-94bc-466b-a4d0-524fc10c2a31",
"tool": "get_reddit",
"error": "upstream_error",
"class": "upstream_error",
"charged_paise": 0,
"message": "The provider rejected this call. Nothing was charged.",
"retryable": false,
"upstream_status": 401,
"upstream_message": "invalid token",
"request_id": "fe4a5c07-a122-457d-8752-bfe86b427407"
}
The headline tools
Four data tools are registered as first-class MCP tools so Claude picks them without a discover_tools round trip. Each takes the tool's own input fields as arguments (the schema from inspect_tool, flattened), gets a confirm argument when it can need confirmation (none does today), and returns exactly what run_tool would. Their descriptions begin with the summary and end with today's price and the ₹0 rule.
| MCP tool | Arguments | Price today | Page |
|---|---|---|---|
search_web | q, limit, country, language, ai_overview | ₹0.14 per call | search_web |
find_email | domain, company, full_name, first_name, last_name, linkedin_handle, max_duration | ₹2.77 per email found; a miss is ₹0 | find_email |
get_social_posts | handle, next_max_id | ₹0.28 per page | get_social_posts |
check_ai_visibility | prompt, country, state, legacy, include, disableWebSearch | ₹0.37 per prompt | check_ai_visibility |
The other four (search_news, verify_email, read_page, get_reddit) run through run_tool; how_to_run on each tool says which.
An agent's loop
check_balanceonce, to confirm the connection.discover_toolswith a keyword when unsure;inspect_toolon the pick. Never guess inputs.quote_toolwhen the cost matters; tell the user.- Run it (a headline tool, or
run_tool) with anidempotency_keywhen a retry is possible and aclient_tagwhen working for a named client. - Report
cost_paise. On an error, follow the error table. The whole guide, written for the agent: skill.md.
This page as Markdown: /docs/mcp.md. Something wrong or missing: hello@parel.si.