SDKs and the MCP server
Both SDKs are thin: every method is one API call and returns the API's JSON unwrapped, so the API reference is the reference for them too. Both read MESHARC_API_KEY from the environment.
Building with LangChain? langchain-mesharc wraps the Python SDK as a document loader and agent tools.
Python#
Python 3.10+, one dependency (httpx), fully typed.
from mesharc import MeshArc, MeshArcError
arc = MeshArc("mesharc_...") # or MeshArc() with MESHARC_API_KEY set
# One URL, waited for: the API holds the request open for the page
page = arc.scrape("https://quotes.toscrape.com/js/", config={"render_js": "always"})
print(page["markdown"][:200], page["credits"], page["verdict"])
# Many URLs, no project: grouped by host, fetched in parallel where allowed
batch = arc.scrape(["https://a.com/", "https://b.com/x"], config={"concurrency": 4})
for row in batch["pages"]:
print(row["url"], row["httpStatus"], row["verdict"], row["credits"])
# What a site declares, before fetching any of it
for u in arc.map("https://docs.example.com"):
print(u["url"], u["lastmod"])
# A whole site, once, with no project to set up first
job = arc.crawl("https://docs.example.com", limit=200, maxDepth=3,
scrapeOptions={"formats": ["markdown", "links"]})
for page in job.pages(): # follows the cursor, keeps up with the crawl
print(page["url"], page["words"])
print(job.status, job.envelope["counts"], job.envelope["creditsUsed"])
project = job.keep(name="Docs", schedule="weekly") # ...and keep it, if it is worth watching
# A site watched over time
project = arc.projects.create("https://docs.example.com", name="Docs", schedule="weekly",
config={"max_pages": 300, "include_paths": ["/docs/*"]})
run = arc.runs.start(project["id"], wait=True)
record = arc.changes(project["id"])
print(record["change"]["counts"])
hits = arc.search(project["id"], '"free shipping" returns') # words in the markdown
hits = arc.search(project["id"], "table.pricing td", mode="selector") # elements in the html
arc.export(project["id"], "pages.jsonl", dataset="markdown")
# The web, searched: ranked organic results, each page read as markdown when asked
res = arc.web_search("python http client", limit=5, scrape=True)
for hit in res["data"]:
print(hit["position"], hit["url"], hit["title"])
# A research question: the agent searches and reads on its own, within a credit cap
run = arc.agent("The monthly price of each plan", urls=["https://example.com/pricing"],
max_credits=200)
run.wait()
print(run.status, run.data, [s["url"] for s in run.sources])
more = run.follow_up("Which plan includes API access?")
# A search kept on a schedule, each run compared with the last
monitor = arc.monitors.create("search", {"query": "mesharc", "sources": ["news"]}, "daily")
| Method | Calls |
|---|---|
extract(url, config, wait, poll, timeout) | POST /playground/extract — one URL with every format |
screenshot(run_id) | GET /playground/{id}/screenshot — the picture a one-URL scrape or extract took (formats with screenshot), as bytes |
scrape(urls, config, webhook_url, formats, wait, …) · scrape_one(url, config, formats, wait, timeout_s, idempotency_key) | POST /scrape |
crawl(url, wait, poll, timeout, idempotency_key, **opts) → Crawl (.status, .envelope, .refresh(), .wait(), .pages(cursor=…), .page(url), .keep(), .cancel()) · get_crawl(id) | POST /crawl, GET /crawl/{id}, …/page, …/keep, DELETE |
map(url, **opts) → rows · map_details(url, search, limit, …) → the envelope | POST /map |
batch(batch_id, formats, wait, …) | GET /scrape/{id} |
projects.list() / create(seed, name, schedule, retention, config) / get / update(project_id, **fields) / delete | /projects |
runs.list(project_id, limit) / get / start(project_id, wait, poll, timeout) / wait / cancel | /projects/{id}/runs |
pages(project_id, run_id) · page(project_id, url, run_id) · changes(project_id, run_id, against) · page_diff(project_id, url, run_id) · search(project_id, q, mode, run_id) · recrawl(project_id, urls) · sources(project_id) · export(project_id, path, dataset, fmt, run_id, urls) · webhook_deliveries(project_id) · test_webhook(project_id) | The project routes |
web_search(query, limit, country, lang, freshness, include_domains, exclude_domains, scrape, news, page, …) · get_search(search_id) · searches(q, limit) | POST /search, GET /search/{id}, GET /search |
agent(prompt, urls, schema, max_credits, max_steps, allowed_domains, webhook, logins, …) → AgentRun (.status, .data, .sources, .wait(), .refresh(), .trace(), .follow_up(prompt), .continue_(), .cancel()) · get_agent(run_id) · agent_runs(status, …) · cancel_agent(run_id) · conversations(q) · conversation(thread_id) | /agent |
agent_batches.preview / start / get / rows / wait / list / cancel / export — the agent over every row of a table | /agent/batch |
monitors.create(kind, request, schedule, …) / list / get / update / pause / resume / run / runs / delete / overview / rows / rows_page / row / row_events / export_rows | /monitors |
triggers.create / list / get / update / delete / fires / preview · proposals.list / approve / dismiss · estimate(kind, schedule, …) | /triggers, /proposals, GET /estimate |
sub_accounts.create / list / get / update / keys / create_key / revoke_key · as_sub_account(sub_account_id) → a client whose every request carries X-MeshArc-Tenant | /orgs/children |
connections.providers / list / create / get / update / test / delete · logins.list / update / test / delete (admin keys) | /connections, /logins |
me() · keys() · create_key(name, scopes, projects, expires_in_days, rpm) · revoke_key(key_id) · usage() · billing() · monitor() · meta() · cancel_batch(batch_id) · get_extract(extract_id) | The workspace routes |
close() | Close the HTTP client |
Errors raise MeshArcError with status, detail, code (validation, rate_limited, plan_limit, not_found, …) and request_id — the id the API put on the response header and in its logs. A job the client stopped waiting for raises MeshArcTimeoutError (also a TimeoutError) with its job_id. Requests time out after timeout seconds (150) and are retried on 429, 502, 503, 504 and network failures when safe to repeat — a GET, a DELETE, or a POST with an idempotency_key= — up to max_retries times (2).
Node#
Node 20+, zero dependencies (native fetch). TypeScript types, ESM and CommonJS builds.
import { MeshArc, MeshArcError } from 'mesharc';
const arc = new MeshArc('mesharc_...'); // or new MeshArc() with MESHARC_API_KEY set
const page = await arc.scrape('https://quotes.toscrape.com/js/', { render_js: 'always' });
console.log((page.markdown as string).slice(0, 200), page.credits, page.verdict);
const batch = await arc.scrape(['https://a.com/', 'https://b.com/x'], { concurrency: 4 });
for (const row of batch.pages) console.log(row.url, row.httpStatus, row.verdict, row.credits);
for (const u of await arc.map('https://docs.example.com')) console.log(u.url, u.lastmod);
const job = await arc.crawl('https://docs.example.com', { limit: 200, maxDepth: 3 });
for await (const p of job.pages()) console.log(p.url, p.words); // follows the cursor
const kept = await job.keep({ name: 'Docs', schedule: 'weekly' });
const project = await arc.projects.create('https://docs.example.com', { name: 'Docs', schedule: 'weekly' });
const run = await arc.runs.start(project.id, { wait: true });
const record = await arc.changes(project.id);
const hits = await arc.search(project.id, 'table.pricing td', 'selector');
const csv = await (await arc.export(project.id, { dataset: 'pages', format: 'csv' })).text();
const res = await arc.webSearch('node fetch retry', { limit: 5, scrape: true });
for (const hit of res.data) console.log(hit.position, hit.url, hit.title);
const run = await arc.agent('The monthly price of each plan', {
urls: ['https://example.com/pricing'], maxCredits: 200,
});
await run.wait();
console.log(run.status, run.data, run.sources.map((s) => s.url));
const more = await run.followUp('Which plan includes API access?');
const monitor = await arc.monitors.create('search', { query: 'mesharc', sources: ['news'] }, 'daily');
| Method | Calls |
|---|---|
extract(url, config?, {wait, poll, timeout}) | POST /playground/extract |
scrape(urls, config?, {webhookUrl, formats, apiTimeoutS, idempotencyKey, …}) · scrapeOne(url, config?, {…}) | POST /scrape |
crawl(url, {limit, maxDepth, …, wait, idempotencyKey}) → Crawl (.status, .envelope, .refresh(), .wait(), .pages() async iterator, .keep(), .cancel()) · getCrawl(id) | /crawl |
map(url, {search, limit}) → rows · mapDetails(url, {…}) → the envelope | POST /map |
batch(batchId, {formats, wait}) | GET /scrape/{id} |
projects.list() / create(seed, {name, schedule, retention, config}) / get / update(id, fields) / delete · runs.list / get / start(id, {wait}) / wait / cancel | /projects |
pages, page, changes, pageDiff, `search(projectId, q, 'content' | 'selector', runId?), recrawl, sources, export(projectId, {dataset, format, runId, urls})→Response, webhookDeliveries(projectId), testWebhook(projectId)` |
webSearch(query, {limit, country, lang, freshness, includeDomains, excludeDomains, scrape, news, page, …}) · getSearch(id) · searches({q, limit}) async iterator | POST /search, GET /search/{id}, GET /search |
agent(prompt, {urls, schema, maxCredits, maxSteps, allowedDomains, webhook, logins, …}) → AgentRun (.status, .data, .sources, .wait(), .refresh(), .trace(), .followUp(prompt), .continue(), .cancel()) · getAgent(runId) · agentRuns({status, …}) · cancelAgent(runId) · conversations({q}) · conversation(threadId) | /agent |
agentBatches.preview / start / get / rows / wait / list / cancel / export — the agent over every row of a table | /agent/batch |
monitors.create(kind, request, schedule, opts?) / list / get / update / pause / resume / run / runs / delete / overview / rows / rowsPage / row / rowEvents / exportRows | /monitors |
triggers.create / list / get / update / delete / fires / preview · proposals.list / approve / dismiss · estimate(kind, schedule, opts?) | /triggers, /proposals, GET /estimate |
subAccounts.create / list / get / update / keys / createKey / revokeKey · asSubAccount(subAccountId) (or new MeshArc(key, { tenant })) → a client whose every request carries X-MeshArc-Tenant | /orgs/children |
connections.providers / list / create / get / update / test / delete · logins.list / update / test / delete (admin keys) | /connections, /logins |
me(), keys(), createKey(name, {scopes, projects, expiresInDays, rpm}), revokeKey, usage(), billing(), monitor(), meta(), cancelBatch(batchId) | The workspace routes |
call(method, path, body?, params?) · raw(...) | Any route |
Errors throw MeshArcError with status, detail, code and requestId; a job the client stopped waiting for throws MeshArcTimeoutError with its jobId. Requests time out after timeoutMs (150 000) and are retried on 429, 502, 503, 504 and network failures when safe to repeat — a GET, a DELETE, or a POST with an idempotencyKey — up to maxRetries times (2).
The MCP server#
The Python package also ships MeshArc as an MCP server, so Claude Desktop, Claude Code, Cursor and any MCP client can search the web, scrape, take a screenshot of a page, crawl, map, set up and change projects, read change records, ask the research agent and keep a search or a question on a schedule, as 23 tools. There is a hosted one at https://mcp.mesharc.dev/mcp -- paste the URL, sign in, approve, and nothing is installed -- or you can run it yourself over stdio with your own key. Either way it sits on top of the Python client, so what an agent gets is what the API gives. A result with many pages in it is an index of the pages read (up to 500, fewer if the budget needs the room), an excerpt of as many as a 60,000-character budget pays for (fifty at most), and a count of each page’s links rather than the links; ask for one page on its own, each body up to 12,000 characters, with get_job(kind="crawl", id=…, url=…), or carry on through a crawl with cursor=. Hosted, a connection approved read-only can read what the workspace has stored — projects, runs, pages, change records, monitors and their rows, get_job — but not fetch a new page, start work or change anything: every tool that does (the web search and the agent among them) reaches the site or alters the workspace, and most of them spend credits, so it answers read_only until the app is reconnected with write access. Python 3.10+. The MCP page walks through setup for each client and shows real conversations.
pip install "mesharc[mcp]"
MESHARC_API_KEY=mesharc_... mesharc-mcp
# Claude Code
claude mcp add mesharc -e MESHARC_API_KEY=mesharc_... -- mesharc-mcp
| Tool | What it does |
|---|---|
scrape_urls(urls, config?, formats?, parse_documents?, full?) | Content for a list of pages; PDFs and Word (.docx) files read as text unless told not to. full=true reads one page with every format |
screenshot_url(url, viewport?, actions?, wait_ms?) | A picture of one page, returned as an image: desktop or mobile, after browser steps and a wait; 5 credits (a render that gives no picture still costs its 4) |
map_site(url, search?, limit?) | The site's URLs from its sitemap |
search_web(query, limit?, country?, lang?, freshness?, include_domains?, exclude_domains?, scrape?) | Search the web: ranked results, kept to named sites when asked, each page as markdown with scrape=true |
crawl_site(url, limit?, max_depth?, include_paths?, …) | A one-shot crawl, pages returned as they land; the paths are globs (/blog/*) |
get_project() | With no project id: every setting an assistant can set, its meaning and default — read before setting one |
list_projects() · get_project(project_id) · create_project(seed or crawl_id, name?, schedule?, config?) · update_project(project_id, name?, schedule?, config?, test_webhook?) | Projects and their settings; crawl_id promotes a one-off crawl, a partial config on update merges, and a key that is not a setting is refused by name. get_project shows the webhook and its last deliveries; test_webhook=true sends it a test; list_projects also says the credits left |
delete_project(project_id, confirm_name) | Delete a project and its history; needs an admin API key, so only the local server can |
archive_project(project_id, confirm_name) | Archive a project: it stops running, frees its place in the plan, and is deleted after 30 days unless restored in the app; what a connected app does in place of a delete |
start_run(project_id, urls?, wait?) · list_runs(project_id, limit?) | Run a project now, or only the pages listed; its runs, newest first |
list_pages(project_id, run_id?, q?, mode?, url?) | A run's pages; with q a search of them; with url one page in full, with its versions |
get_changes(project_id, run_id?, against?) | The change record, against the run before or any run named with against |
run_agent(prompt, urls?, schema?, allowed_domains?, max_credits?, max_steps?) · continue_agent(id, max_credits?, max_steps?) | Hand a research question to the agent, which comes back as a job; carry on a run that stopped at its credit limit |
create_monitor(kind, query or prompt, schedule, …) · list_monitors(kind?, monitor_id?) · pause_monitor(monitor_id, resume?) · get_monitor_rows(monitor_id, changes?, …) | Keep a web search or an agent question on a schedule, each run compared with the last; follow an agent monitor's records |
get_job(kind, id, …) · cancel_job(kind, id, project_id?) | Follow a long job — a crawl, run, batch, web search, full read or agent run; stop one |
The clients are open source: mesharc-python and mesharc-node.