Messora MCP Server

Messora exposes a Model Context Protocol (MCP) remote server over Streamable HTTP. It lets LLM agents (Claude, Codex, Cursor and other MCP clients) call scrape, crawl, search and query jobs and usage — reusing the same account, API key and credit pool as the REST API.

Endpoint

Resource	URL
MCP	`https://mcp.messora.dev/mcp`
Health	`https://mcp.messora.dev/health`

The /health endpoint is independent of the backend and returns {"status": "ok", "service": "messora-mcp"} without requiring authentication.

Authentication

The MCP uses only the Authorization: Bearer header:

Authorization: Bearer $MESSORA_API_KEY

The X-API-Key header used by the REST API is not accepted by the MCP. Always use Authorization: Bearer.

You need a Messora API key. If you don’t have one yet, create it at www.messora.dev/auth/signup → API Keys.

Configuring clients

Claude Desktop

Claude Desktop uses a JSON config at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "messora": {
      "type": "http",
      "url": "https://mcp.messora.dev/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

Restart Claude Desktop after saving. The Messora tools appear in the tool picker.

Claude Desktop does not support environment variable interpolation in config. Use a placeholder and replace it, or set the key directly — the file is local and not versioned.

Cursor

Cursor uses an .mcp.json file at the project root or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "messora": {
      "type": "http",
      "url": "https://mcp.messora.dev/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

Restart Cursor or run Cursor → Settings → MCP → Refresh to load the server.

Codex CLI

Codex uses a config.toml file at ~/.codex/config.toml:

[mcp_servers.messora]
url = "https://mcp.messora.dev/mcp"
bearer_token_env_var = "MESSORA_API_KEY"

Export the API key before starting Codex:

export MESSORA_API_KEY="your-api-key-here"

MCP Inspector

export MESSORA_API_KEY="your-api-key-here"
npx @modelcontextprotocol/inspector

In the Inspector, configure:

Transport type: Streamable HTTP
URL: https://mcp.messora.dev/mcp
Authentication: Bearer token
Token env var: MESSORA_API_KEY

Never hardcode your API key in versioned config files. For Codex, always use an environment variable ($MESSORA_API_KEY). For Claude Desktop and Cursor, the config is local (not versioned) — replace the placeholder with your key.

Available tools

The server exposes exactly five tools:

`scrape_url`

Extracts content from a URL. Consumes credit only when the backend returns scrape_status = success.

Parameter	Type	Default	Description
`url`	string (URI)	required	Target URL
`formats`	`["markdown"]`	`["markdown"]`	Formats: `markdown`, `json`, `raw`
`json_schema`	object	—	Required if `formats` includes `json`
`render_js`	boolean	`false`	Render JavaScript
`only_main_content`	boolean	`false`	Main content only
`timeout`	int (1–180)	`60`	Timeout in seconds
`max_pages`	int (1–50)	`1`	Max pages
`parse_pdf`	boolean	`true`	Process PDFs
`tags`	string[]	—	Up to 10 tags (64 chars each)

`start_crawl`

Starts an async crawl and returns job_id. Poll get_job until the state becomes SUCCESS, FAILURE or REVOKED.

Parameter	Type	Default	Description
`url`	string (URI)	required	Seed URL
`max_pages`	int (1–50)	required	Page cap
`max_depth`	int ≥ 0	—	Max BFS depth
`only_main_content`	boolean	`true`	Main content only
`timeout_ms`	int (1000–300000)	`60000`	Per-page timeout
`tags`	string[]	`[]`	Usage tags

`start_search`

Starts an async premium search and returns job_id.

Parameter	Type	Default	Description
`query`	string	required	Search query
`num_results`	int (10–100)	`10`	Number of results
`country`	string (ISO alpha-2)	—	E.g. `BR`, `US`
`freshness`	`day\|week\|month\|year\|any`	—	Recency filter
`tags`	string[]	—	Up to 10 tags
`query_fanout`	boolean	`true`	LLM-expand the query into up to 5 variants. `false` searches only the raw query — faster, with 1 fewer LLM call (relevance scoring still runs)
`use_cache`	boolean	`false`	Reuse a complete result from the last 10 minutes for the same query and filters

`get_job`

Queries the state of a crawl or search job.

Parameter	Type	Description
`job_id`	string	UUID returned by `start_crawl` or `start_search`

States: PENDING → STARTED → SUCCESS | FAILURE | REVOKED

We recommend polling every 2 seconds with backoff. The MCP adapter does not perform internal polling or automatic retries of charged operations.

`get_usage`

Queries plan, credits used and account balance. No product arguments. Same payload as the REST GET /account/usage.

Complete walkthrough: All five tools in one flow

The five tools have different patterns: sync (scrape_url), async polling (start_crawl, start_search → get_job), and query (get_usage). Here’s a realistic sequence:

// 1. Sync scrape: single URL, immediate response
const singlePage = await mcp.call_tool('scrape_url', {
  url: 'https://example.com/article',
  formats: ['markdown', 'json'],
  json_schema: { type: 'object', properties: { title: { type: 'string' } } }
})
// → {"ok": true, "data": {"markdown": "# Article...", "json": {"title": "..."}, ...}, "success": true}

// 2. Async crawl: multiple URLs, returns job_id, poll until complete
const crawlJob = await mcp.call_tool('start_crawl', {
  url: 'https://example.com',
  max_pages: 10
})
// → {"ok": true, "data": {"job_id": "abc-123", "status": "PENDING"}, ...}

// 3. Poll job status
let jobStatus = await mcp.call_tool('get_job', {
  job_id: crawlJob.data.job_id
})
// → {"ok": true, "data": {"status": "STARTED", "meta": {"pages_done": 3, "max_pages": 10}}, ...}

// Repeat #3 every 2 seconds until status = "SUCCESS" or "FAILURE"
while (jobStatus.data.status === 'STARTED') {
  await new Promise(r => setTimeout(r, 2000))
  jobStatus = await mcp.call_tool('get_job', { job_id: crawlJob.data.job_id })
}
// → {"ok": true, "data": {"status": "SUCCESS", "results": [...], "credits_used": 10}, ...}

// 4. Async search: similar to crawl — job_id + polling
const searchJob = await mcp.call_tool('start_search', {
  query: 'machine learning',
  num_results: 20
})
// → {"ok": true, "data": {"job_id": "xyz-789", "status": "PENDING"}, ...}

// Poll until success (same pattern as crawl)
let searchStatus = await mcp.call_tool('get_job', { job_id: searchJob.data.job_id })
// → eventually {"status": "SUCCESS", "results": [{...}, ...]}

// 5. Query usage: no params, immediate response
const usage = await mcp.call_tool('get_usage', {})
// → {"ok": true, "data": {"plan": "pro", "credits_used": 1050, "remaining_credits": 1450}, ...}

When to use each:

scrape_url — one URL, need result now (markdown/structured JSON/raw HTML)
start_crawl + get_job — many URLs on same domain, in background, final batch of results
start_search + get_job — search query across indexed content, in background
get_usage — check account plan and credit balance before/after bulk operations

Async flow: `start_*` → `get_job`

Crawl and search are async in the backend. The recommended flow is:

start_crawl(url, max_pages=3)
  → {"job_id": "d8cc042a-dcbb-4f8b-a159-91fd47d060f9", "status": "PENDING", "next_action": "Call get_job..."}

get_job(job_id="d8cc042a-dcbb-4f8b-a159-91fd47d060f9")
  → {"status": "STARTED", "meta": {"pages_done": 1, "max_pages": 3}}

get_job(job_id="d8cc042a-dcbb-4f8b-a159-91fd47d060f9")
  → {"status": "SUCCESS", "credits_used": 3, "results": [...]}

Response size

Every tool response is capped at 100,000 characters. If it exceeds that, text fields (markdown, rawHtml) are truncated while preserving structure, status, metering and valid JSON:

{
  "ok": true,
  "data": { "status": "SUCCESS", "credits_used": 3, "results": [...] },
  "output": { "truncated": true, "original_chars": 250000, "returned_chars": 99500 }
}

Errors

HTTP	MCP code	Retry	Meaning
401	`missing_api_key`	no	Missing credential
402	`insufficient_credits`	no	Insufficient credits
403	`invalid_or_revoked_api_key`	no	Invalid or revoked key
404	`not_found`	no	Nonexistent job or wrong account
422	`validation_error`	no	Invalid input
429	`rate_limit_exceeded`	yes	Rate limit hit (preserves `Retry-After`)
5xx	`backend_unavailable`	yes	Temporary backend failure
—	`backend_timeout`	yes	Network timeout

On a non-2xx response the adapter discards the backend body entirely and derives error.message from the HTTP status alone. Branch on error.code, never on error.message:

HTTP	`error.message`
401	`Authentication required`
402	`Insufficient credits`
403	`Invalid or revoked API key`
404	`Resource not found`
422	`Invalid request parameters`
429	`Rate limit exceeded`
other 4xx	`Request rejected by the backend`
5xx	`Temporary backend failure`

data.json always holds exactly the fields your json_schema declares — the backend never injects extra keys into it, including a field named error. If extraction fails entirely, every declared field is null and a sibling field, data.json_extraction_error_code (currently only "extraction_failed"), reports it instead. When that code is present the MCP adds data.json_extraction_error_message with the fixed English text "Structured extraction failed for this schema. Try again or adjust json_prompt/json_schema.". If your schema declares its own error property, it is never touched — that field only ever holds what your schema requested, success or failure. _extraction_failed is reserved for this internal signal and rejected as a json_schema property name (validation_error). Input the adapter validates itself (duplicate formats, json_schema missing for the json format, pdf_ocr without parse_pdf, overlapping include_domains/exclude_domains, malformed job_id) returns validation_error with a specific message naming the offending field. A 2xx body is forwarded, so system-generated text inside it is normalized to English instead: a job in FAILURE returns the fixed data.error = "The job could not be completed. Try again.", and a search job in STARTED reports meta.stage as starting or running. Extracted web content (results) is never rewritten.

The MCP is a thin adapter: auth, billing, rate limiting and jobs belong to the FastAPI backend. The same limits and costs as the REST API apply.

Getting started

Integrations

Playground

MCP Server

Messora MCP Server

Endpoint

Authentication

Configuring clients

Claude Desktop

Cursor

Codex CLI

MCP Inspector

Available tools

`scrape_url`

`start_crawl`

`start_search`

`get_job`

`get_usage`

Complete walkthrough: All five tools in one flow

Async flow: `start_*` → `get_job`

Response size

Errors

​Messora MCP Server

​Endpoint

​Authentication

​Configuring clients

​Claude Desktop

​Cursor

​Codex CLI

​MCP Inspector

​Available tools

​scrape_url

​start_crawl

​start_search

​get_job

​get_usage

​Complete walkthrough: All five tools in one flow

​Async flow: start_* → get_job

​Response size

​Errors

Messora MCP Server

Endpoint

Authentication

Configuring clients

Claude Desktop

Cursor

Codex CLI

MCP Inspector

Available tools

`scrape_url`

`start_crawl`

`start_search`

`get_job`

`get_usage`

Complete walkthrough: All five tools in one flow

Async flow: `start_*` → `get_job`

Response size

Errors