Plug your agents straight in

Start here

Choose how to connect

MCP gives your agent tools to find endpoints and retrieve data. Monocrawl runs the data requests; your AI app decides when to call the tools. You need an account for account information and retrieval. Public catalogue discovery at /mcp needs no account.

Start with a recorded search and full-result retrieval or batch transcripts. Monthly and annual plans include a monthly credit allowance. Active paid subscribers can buy extra credits in Billing; purchased credits never expire.

After connecting, follow your first data request. For an existing connection that is failing, go to troubleshooting.

Connect

Add Monocrawl, then sign in

Give the setup command to your coding agent, then approve the connection in your browser. The helper saves the credential directly to your app without displaying it. Requires Node.js 18.17 or newer. Paste into your agent or run in a terminal; the connection and skill are installed together.

npx -y monocrawl-cli@latest init --agent claude

npx -y monocrawl-cli@latest init --agent codex

Open setup to connect your app and check access. Developer details contains server addresses, the skill and advanced options. All client instructions and CLI setup.

Ask your connected agent to check your balance. get_balance is free; paid retrieval and monitors are not part of setup.

Claude.ai

Connect directly in Claude with browser sign-in. No terminal, Node.js or API key required.

1. Open Customize → Connectors in Claude, then + → Add custom connector.
2. Name it Monocrawl and paste the server URL below. Add it, select Connect and approve Monocrawl in your browser.

https://www.monocrawl.com/mcp/oauth

Start a new Claude chat. Select + → Connectors and enable Monocrawl for that conversation.

On Team or Enterprise, a workspace owner must add the connector first.

Client documentation

ChatGPT

Connect directly in ChatGPT with OAuth browser sign-in. No terminal, Node.js or API key required.

1. Open Settings → Security and login and turn on Developer mode.
2. Open Plugins, select + and name the connection Monocrawl. Paste the server URL below, choose OAuth if asked, then create the connection and sign in.

https://www.monocrawl.com/mcp/oauth

Start a new ChatGPT conversation and add Monocrawl from the tools menu. If the tools are missing, open the connection in Plugins and select Refresh.

Developer mode availability depends on your account and workspace policy.

Client documentation

CLI

Setup command options

Choose claude, codex, cursor, vscode, grok or opencode with --agent. Use --all only when you want every detected client configured. Existing unrelated MCP connections are preserved.

Use --no-browser to print the approval link instead of opening it, --oauth for the client’s built-in OAuth flow, or --skip-auth to install OAuth configuration without signing in. Configuration alone does not verify access. Reconnect or start a new client session, enable Monocrawl’s tools and ask it to check your balance. See client-specific reconnect instructions.

First request

Discover, check the price, then retrieve

Try this prompt in your connected agent. It checks access for free and asks the agent to inspect the current endpoint before spending:

Check my Monocrawl balance and connection spending limit. Find the GitHub profile endpoint and inspect its current parameters, price and MCP availability. If it is available and costs at most 1 credit, fetch the public profile for torvalds once. Use a 1-credit maximum and a unique idempotency key. Show the result, actual credits used, request ID and any warnings. If it needs more than 1 credit, stop and tell me.

The equivalent tool calls are below. These objects contain a tool name and its arguments; an MCP client wraps them in tools/call. They are not REST request bodies.

1. Check access and funds. get_balance is free, even when the connection spending cap has been reached. A successful call through your agent verifies that this chat has loaded the connection.
   get_balance — tool call

   {
     "name": "get_balance",
     "arguments": {}
   }

2. Find an endpoint. Narrow the catalogue by platform or search text. Compact results omit parameter schemas and use less context.
   list_endpoints — tool call

   {
     "name": "list_endpoints",
     "arguments": {
       "platform": "github",
       "search": "profile",
       "compact": true,
       "limit": 5
     }
   }

3. Inspect the contract. Read the current credit_cost, required parameters and availability fields. get_endpoint also returns an example request.
   get_endpoint — tool call

   {
     "name": "get_endpoint",
     "arguments": {
       "id": "github/profile"
     }
   }

4. Make one bounded request. This example permits at most one credit; that is your spending ceiling, not a promise about today’s price. If the required reservation is higher, it is refused before spending. Use a fresh idempotency key for your own new request and retain it for retries of that same request.
   call_endpoint — tool call

   {
     "name": "call_endpoint",
     "arguments": {
       "platform": "github",
       "endpoint": "profile",
       "params": {
         "handle": "torvalds"
       },
       "max_credits": 1,
       "idempotency_key": "github-profile-example-1"
     }
   }

Ordinary call_endpoint calls execute immediately and may spend credits. There is no general preview or confirmation flag for retrieval. Use your client’s approval settings and the credit controls below when a person must approve each call.

Tool reference

Argument types and supported operations

The tables below use the server’s tool schemas. A tool argument such as max_credits is a JSON number, while every value inside call_endpoint.params must be a string. For an endpoint that accepts a limit, send "limit": "25" inside params. Send "compact": true and "limit": 25 as native types to list_endpoints. Include only parameters declared by the selected endpoint.

If an endpoint accepts a JSON-encoded parameter, serialize its object or array into a string inside params. Read the endpoint’s parameter description before sending it. The platform is an ID such as github; endpoint is the operation inside it, such as profile, without a URL or /v1 prefix.

The read tool supports reviewed data operations, including job and browser-session status. Job creation or cancellation and browser controls use the dedicated action tools below. Cohort management retains its documented dashboard or REST workflow.

Actions

Preview jobs and browser controls

Read mcp_tool from get_endpoint. Use start_data_job for web crawl, batch-scrape and agent jobs or TripAdvisor attraction and restaurant reviews. Omit confirm for a free estimate. To execute, send boolean confirm: true, an idempotency_key and an authorized max_credits ceiling. Parameters inside params remain strings.

{
  "name": "start_data_job",
  "arguments": {
    "platform": "web",
    "endpoint": "crawl",
    "params": {
      "url": "https://example.com",
      "limit": "1"
    }
  }
}

After reviewing the returned estimate and proposed parameters, repeat the same arguments with those three execution controls. Keep the same idempotency key after a lost response; changing it can duplicate work and charges. The ceiling limits this action's reservation, not all future actions.

A job receipt means work was accepted. Poll its returned job id with call_endpoint, platform web, endpoint jobs/get, and params.job_id. Reads cost zero credits; bound polling and honor retry delays. Inspect terminal status, item outcomes and refund_status. cancel_web_job previews the current job before confirmation; cancellation does not guarantee a refund for work already attempted.

create_browser_session uses the same preview, confirmation, replay-key and credit-ceiling rules. Read its current price and TTL limits from discovery. execute_browser_session previews the owned session and proposed code without running it; confirmed execution can click, type, submit forms or change a website. Review the exact code and URL. close_browser_session previews the session, then releases it when confirmed; closing does not refund creation.

Browser-code execution is charged separately from session creation and requires max_credits; inspect its price with get_endpoint. Execution and cancellation of existing resources also require a replay key. Job and session operations use the authenticated account's ownership checks. These controls operate a hosted browser, not the machine running your MCP client. Large action results use the same stored-result retrieval as data reads.

Results

Read the data, charge and error

A raw tools/call response wraps the tool result under result. Read result.structuredContent for the Monocrawl payload. result.content also contains a text copy for clients that consume text. Most agent apps show the tool result without the outer JSON-RPC wrapper.

This illustrative response has a shortened profile and example charge/balance values. Read the returned receipt for the actual values.

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"success\":true,\"platform\":\"github\",\"endpoint\":\"/v1/github/profile\",\"data\":{\"handle\":\"torvalds\",\"name\":\"Linus Torvalds\"},\"credits_used\":1,\"credits_remaining\":999,\"request_id\":\"req_4f2b8c1d09ae37b562\",\"cached\":false}"
      }
    ],
    "structuredContent": {
      "success": true,
      "platform": "github",
      "endpoint": "/v1/github/profile",
      "data": {
        "handle": "torvalds",
        "name": "Linus Torvalds"
      },
      "credits_used": 1,
      "credits_remaining": 999,
      "request_id": "req_4f2b8c1d09ae37b562",
      "cached": false
    },
    "isError": false
  }
}

A routed failure can also arrive inside HTTP 200. This abbreviated example shows a connection credit-cap refusal:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"success\":false,\"error\":{\"type\":\"KEY_LIMIT_EXCEEDED\",\"message\":\"This request would exceed the credit limit for this key or connection.\",\"status\":402},\"credits_used\":0,\"request_id\":\"req_9c2e41a7d0b35f8e16\"}"
      }
    ],
    "structuredContent": {
      "success": false,
      "error": {
        "type": "KEY_LIMIT_EXCEEDED",
        "message": "This request would exceed the credit limit for this key or connection.",
        "status": 402
      },
      "credits_used": 0,
      "request_id": "req_9c2e41a7d0b35f8e16"
    },
    "isError": true
  }
}

Protocol and authentication failures can instead contain a top-level error with a numeric JSON-RPC code. Tool-validation failures may omit normal receipt fields. Public discovery returns a smaller payload with success, data and credits_used: 0, without an account balance. Handle these cases separately; do not assume every error is a full API envelope. See API errors and response contracts.

More results

Continue the correct kind of page

Stored evidence: large responses include complete preview rows where they fit and data.stored_result.id. Use get_result with mode: "rows" for up to 100 intact rows per 256 KiB page in structuredContent.data.items. Follow the returned cursor with the same mode; select a returned JSON-pointer path when there are several collections. Bodies and nested comments are not split. An oversized row is explicitly blocked and must be retrieved through the full JSON download or legacy text mode. stored_result.download.url returns the entire original JSON with API-key header authentication, private/no-store headers and a SHA-256; never put a credential in that URL. Retrieval is free, requires the same account and expires after 24 hours. Original credits in the downloaded envelope describe the original request, not a new charge. Legacy/default text mode still returns data.text fragments: concatenate them before parsing JSON. Storage remains capped at 8 MiB per result and 32 MiB per account; storage failure returns the complete original response with a warning. These are stored rows, not new source pages. Do not repeat the paid request.

Catalogue pages: list_endpoints returns data.items, the current page’s count, a matching total and cursor. Pass the cursor unchanged with the same platform and search filters. The default is 25 entries; the maximum is 100. Use compact: true to reduce response size, then inspect chosen endpoints individually. Catalogue pages are free.

Only continue when the previous page supplies a cursor. For the same filters used in the walkthrough:

{
  "platform": "github",
  "search": "profile",
  "compact": true,
  "limit": 5,
  "cursor": "COPY_CURSOR_FROM_PREVIOUS_CATALOGUE_PAGE"
}

Data pages: use the chosen endpoint’s continuation fields inside call_endpoint.params. Many lists return a cursor; bundles can return named collections with next_params. Keep original filters, pass opaque values unchanged and use supplied next parameters together. A new data page is a new logical request: use a new idempotency key and apply a credit ceiling again.

A missing data cursor does not prove that all history was retrieved. Inspect has_more, warnings, source limits and any complete, partial or legs metadata. Catalogue pagination and source-data pagination are separate contracts. See pagination and caching.

Costs

Account funds, connection cap and per-call ceiling

MCP uses the same account billing as REST. Discovery and balance checks are free. A fresh paid retrieval uses the endpoint’s current charge; cached responses and failed retrievals follow the API’s refund and caching rules. An uncertain outcome still needs reconciliation; a lost connection is not proof of a refund.

data.connection.credits_remaining is remaining room under the connection cap; data.credits_remaining is the account balance. A null connection limit means no credential-specific cap, not unlimited account funds. Raising one limit does not raise the others. The server does not automatically seek your approval to increase a ceiling.

Key and account limits follow your subscription. Starter begins at 600 requests/minute and 50 concurrent requests per key; Pro, Growth and Business increase both key and account capacity. Free accounts share their limits across keys. Anonymous discovery has a separate abuse limit. Protocol traffic consumes request headroom too. Read the rate-limit guide for the complete plan table and retry behavior.

Recovery

Retry without starting a second paid request

1. Set idempotency_key before the first paid call. Use 1–255 printable, non-space ASCII characters; a UUID works. A JSON-RPC id only pairs a response with a request and does not protect billing.
2. After a timeout or lost response, keep the same account, endpoint, parameters, max_credits and idempotency key. Check the usage receipt before starting new work. The local bridge makes one POST and never retries automatically; other clients can behave differently.
3. A completed request can replay its saved result. x-idempotent-replay: true marks a replay when your client exposes response headers. The saved charge is the original request’s charge, not an additional debit; the saved balance is historical.
4. If the error reason is idempotency_in_progress, wait and inspect the existing outcome. If arguments differ, correct the accidental mismatch; use a new key only for a genuinely new action. Ordinary replay records last 24 hours; unresolved recovery may keep a request protected longer. An expired key is not permanent duplicate protection.
5. Respect retry-after or retry_after_seconds when supplied for a temporary refusal. Limit retries and add backoff. If credits_used is null and error.details.billing_status is pending_reconciliation, the final charge remains unknown. Keep the receipt and reuse the same key; do not report zero cost or start a fresh paid action to check.

For raw HTTP clients, the Idempotency-Key header is also accepted; if you send both it and the tool argument, their values must match. When replay storage is unavailable, a protected request is refused before execution with an API error status of 503 and x-idempotency-status: unavailable. MCP wraps that routed error in an HTTP 200 tool response with isError: true; retry later with the same key. See the API retry contract.

Troubleshooting

Find the failure, then take the next step

For help, include the client and version, time of failure, tool/endpoint, error type and request_id if supplied. Remove keys, tokens and private request data from diagnostics before contacting support.