Three doors, one API
Monocrawl requires no proprietary SDK. Framework examples below do require the named packages. Pick the door that fits the tool: the hosted MCP server at https://www.monocrawl.com/mcp for agent runtimes, the OpenAPI document at /openapi.json for anything that imports specs, and plain HTTP for everything else. The MCP server deliberately exposes a few generic tools (list_endpoints, get_endpoint, call_endpoint, get_balance) plus named monitor tools, rather than hundreds of per-endpoint tools — your agent’s context stays small and endpoint discovery happens at runtime, free.
Claude Code
One command:
claude mcp add --transport http monocrawl https://www.monocrawl.com/mcp \ --header "x-api-key: mn_your_key_here"
Claude can then browse the catalogue and execute endpoints itself. There is also an installable skill document at /agent-onboarding/SKILL.md and an agent-readable API summary at /v1/utility/llms (also served at /llms.txt) if you prefer prompt-level onboarding without MCP.
Cursor
Cursor accepts this streamable-HTTP MCP configuration. Put it in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):
{
"mcpServers": {
"monocrawl": {
"url": "https://www.monocrawl.com/mcp",
"headers": { "x-api-key": "mn_your_key_here" }
}
}
}On /mcp, Authorization: Bearer is an alternative to x-api-key. Keep a config containing your real key out of source control. See Cursor’s MCP setup.
Codex
Codex uses TOML, not the Cursor JSON above. Add this to your Codex configuration and set MONOCRAWL_API_KEY in the environment that launches it:
[mcp_servers.monocrawl]
url = "https://www.monocrawl.com/mcp"
env_http_headers = { "x-api-key" = "MONOCRAWL_API_KEY" }See the official Codex MCP configuration guide for configuration locations and client setup.
n8n
No community node needed — the built-in HTTP Request node is the whole integration:
1. Add an "HTTP Request" node
2. Method: GET
URL: https://www.monocrawl.com/v1/tiktok/profile
3. Query parameters: handle = {{ $json.handle }}
4. Headers: x-api-key = mn_your_key_here
(store the key as an n8n credential, not inline)
5. The response is one JSON envelope — data sits at {{ $json.data }}For normal JSON endpoint responses, an “IF {{ $json.success }}” node handles errors for every workflow, and credits_remaining, when present, lets a workflow watch its budget. By default n8n can stop on non-2xx responses; enable the HTTP Request node’s Never Error option to branch on API error bodies, and handle connection failures separately. If you also enable Include Response Headers and Status, read the envelope under $json.body instead.
LangChain
Import the OpenAPI document into your toolkit of choice, or — usually better for context size — give the agent one thin function and let it discover endpoints at runtime:
// Framework-neutral helper; wrap it in your LangChain version's tool API.
// Discover endpoints via /v1/utility/endpoints (0 credits).
export const monocrawl = async (path, params) => {
const key = process.env.MONOCRAWL_API_KEY;
if (!key) throw new Error('Set MONOCRAWL_API_KEY on your server.');
const url = new URL('https://www.monocrawl.com/v1/' + path);
for (const [k, v] of Object.entries(params ?? {})) url.searchParams.set(k, v);
const res = await fetch(url, { headers: { 'x-api-key': key } });
const body = await res.json();
if (!res.ok || !body.success) throw new Error(body.error?.message ?? 'Monocrawl request failed');
return body.data;
};Vercel AI SDK
For AI SDK versions using inputSchema (5+), install ai and zod; the loop also needs @ai-sdk/openai and its provider credential. One tool covers the API. Define it once, give it to generateText or streamText, and the model discovers endpoints, reads their parameters and prices, and calls them — all against your key, all metered like any other call.
API shape: AI SDK tool reference.
import { tool } from 'ai';
import { z } from 'zod';
export async function requestMonocrawl({ platform, endpoint, params = {} }) {
const key = process.env.MONOCRAWL_API_KEY;
if (!key) throw new Error('Set MONOCRAWL_API_KEY on your server.');
const url = new URL(`https://www.monocrawl.com/v1/${platform}/${endpoint}`);
for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
const res = await fetch(url, { headers: { 'x-api-key': key } });
const body = await res.json();
if (!res.ok || !body.success) throw new Error(body.error?.message ?? 'Monocrawl request failed');
return body;
}
export const monocrawlCall = tool({
description:
'Call any Monocrawl endpoint. Discover endpoints first with platform="utility", endpoint="endpoints" (free).',
inputSchema: z.object({
platform: z.string(),
endpoint: z.string(),
params: z.record(z.string(), z.string()).default({}),
}),
execute: requestMonocrawl,
});The free discovery endpoints (utility/endpoints, utility/endpoint) mean the model reads parameter tables and prices before it spends a credit — the same confirmation-before-cost pattern our own dashboard assistant uses. The following prompt asks the agent to discover before calling and never answer a needs_confirmation response by retrying with confirm — report the estimate and ask. A prompt is not an approval gate: this generic tool can execute immediately, including billable or mutating GET operations. Use an allowlist, client approval controls and a per-key spending cap before exposing it to an unattended agent.
import { generateText, stepCountIs } from 'ai';
import { openai } from '@ai-sdk/openai';
import { monocrawlCall } from './monocrawl-tool';
const result = await generateText({
model: openai('gpt-4.1'),
tools: { monocrawlCall },
stopWhen: stepCountIs(6),
system:
'You have Monocrawl. Discover with platform="utility", endpoint="endpoints" before calling ' +
'anything else. Every /v1 response is real data or an error, never a sample. If a response ' +
'contains needs_confirmation, do not retry with confirm — report the estimate and ask.',
prompt: 'Compare the follower counts of @nasa on TikTok and Instagram.',
});
console.log(result.text);Monitors go through the same tool. Creating one spends credits on a schedule, so ask for the plan first, let a person approve the estimate, then create. Findings come back with evidence links and receipts; pausing is a status change, not a deletion.
import { requestMonocrawl } from './monocrawl-tool';
// 1. Preview only — no monitor is created, no customer credits are charged.
const plan = await requestMonocrawl({
platform: 'monitors', endpoint: 'preview',
params: { query: 'Monzo', purpose: 'complaints', schedule_minutes: '360' },
});
// Inspect plan.data, resolve any ambiguous subject and review the estimate.
console.log(plan.data);
// Stop here. Run the following block separately, only after human approval.
// 2. A person approved the estimate. Create it (1 credit) with the same parameters.
async function createApprovedMonitor() {
const created = await requestMonocrawl({
platform: 'monitors', endpoint: 'create',
params: { query: 'Monzo', purpose: 'complaints', schedule_minutes: '360', name: 'Monzo complaints' },
});
// 3. Reads may be empty until a scheduled check has completed.
const findings = await requestMonocrawl({
platform: 'monitors', endpoint: 'findings',
params: { id: created.data.id, unseen: 'true' },
});
// Pause without deleting: status is the only change.
await requestMonocrawl({ platform: 'monitors', endpoint: 'update', params: { id: created.data.id, status: 'paused' } });
return findings;
}
// Invoke createApprovedMonitor() only after approval; it is not called by this example.Prefer the hosted MCP server if your runtime speaks it: the monitor operations are exposed there as named tools (create_monitor, run_monitor, delete_monitor and friends) with the confirmation rule enforced server-side, for those named operations. Generic call_endpoint requests can still run immediately and spend; updates can resume scheduled spending. The flag is not proof of human consent—your client must obtain that.