Integrations

Build an integration

Start with the agent quickstart, or use a complete guide for n8n, LangChain or Vercel AI SDK. The framework guides include runnable examples with an endpoint allowlist, current-price inspection and credit limits. AI agent integration explains Markdown and MCP documentation access.

Connect your AI to Monocrawl

Coding agents connect to https://www.monocrawl.com/mcp with an API key. Claude.ai and ChatGPT use browser sign-in in the Chat apps guides. Open setup.

After connecting, ask your agent to check your Monocrawl balance. That tool call is free. Continue to the dashboard whenever you like.

OpenClaw · Hermes · Gemini CLI · Claude Code · Codex · Cursor · VS Code · Grok · OpenCode · Claude.ai · ChatGPT

Claude Code

Using the Claude desktop app’s Code tab, or no claude command? Quick install writes the configuration directly and only requires Node.js 18.17 or later. Rerun it if your saved key was revoked, approve the replacement in your browser, then start a new Code session.

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

Connect to https://www.monocrawl.com/mcp with a key from API keys.

This command requires the Claude Code CLI on your PATH. Using the Claude desktop app’s Code tab, or seeing “claude is not recognized”? Use Quick install in Integrations instead: it only requires Node.js 18.17 or later. Otherwise replace mn_your_key_here with your API key locally. Use /mcp to check the connection. Keep the key out of shared files and screenshots.

claude mcp add --transport http --scope user monocrawl https://www.monocrawl.com/mcp --header "x-api-key: mn_your_key_here"

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

claude mcp add --transport http --scope user monocrawl https://www.monocrawl.com/mcp/oauth
claude mcp login monocrawl

In Claude Code, run /mcp, select monocrawl and reconnect. If it is missing, exit and reopen Claude Code. Then ask: “Check my Monocrawl balance.”

Client documentation

Codex

Connect to https://www.monocrawl.com/mcp with a key from API keys.

Add or update this server table. Set MONOCRAWL_API_KEY in the environment that launches Codex, then restart the client. The variable contains your API key, not the word Bearer.

[mcp_servers.monocrawl]
url = "https://www.monocrawl.com/mcp"
bearer_token_env_var = "MONOCRAWL_API_KEY"

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

codex mcp add monocrawl --url https://www.monocrawl.com/mcp/oauth
codex mcp login monocrawl

In the desktop app, open Settings → MCP servers and select Restart. In the IDE extension, select Restart extension. For the CLI, exit and run codex again. Then ask: “Check my Monocrawl balance.”

Client documentation

Cursor

Connect to https://www.monocrawl.com/mcp with a key from API keys.

Merge this server into your personal configuration. Set MONOCRAWL_API_KEY in Cursor’s environment, then reload the client and check its MCP settings.

{
  "mcpServers": {
    "monocrawl": {
      "url": "https://www.monocrawl.com/mcp",
      "headers": {
        "x-api-key": "${env:MONOCRAWL_API_KEY}"
      }
    }
  }
}

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

{
  "mcpServers": {
    "monocrawl": {
      "url": "https://www.monocrawl.com/mcp/oauth"
    }
  }
}

In Cursor, open Customize → MCP and toggle monocrawl off, then on. Open a new agent chat. Then ask: “Check my Monocrawl balance.”

Client documentation

VS Code

Connect to https://www.monocrawl.com/mcp with a key from API keys.

Run this command from VS Code’s Command Palette, then merge the servers and inputs below. Start the server to enter your key in a masked prompt. This setup targets the editor’s MCP integration.

{
  "servers": { "monocrawl": {
    "type": "http",
    "url": "https://www.monocrawl.com/mcp",
    "headers": { "x-api-key": "${input:monocrawl-key}" }
  }},
  "inputs": [{
    "id": "monocrawl-key", "type": "promptString",
    "description": "Monocrawl API key", "password": true
  }]
}

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

{
  "servers": {
    "monocrawl": {
      "type": "http",
      "url": "https://www.monocrawl.com/mcp/oauth"
    }
  }
}

In VS Code, run MCP: List Servers from the Command Palette, select monocrawl, then stop and start it. Open a new Agent chat and enable its tools. Then ask: “Check my Monocrawl balance.”

Client documentation

Grok

Connect to https://www.monocrawl.com/mcp with a key from API keys.

Merge this into your active personal configuration, keeping your other servers. Replace mn_your_key_here with your API key locally. Use your profile’s config path if you have a custom profile.

[mcp_servers.monocrawl]
url = "https://www.monocrawl.com/mcp"

[mcp_servers.monocrawl.http_headers]
Authorization = "Bearer mn_your_key_here"

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

grok mcp add --transport http monocrawl https://www.monocrawl.com/mcp/oauth

Exit the running Grok CLI session, then run grok again to load the saved connection. Then ask: “Check my Monocrawl balance.”

Client documentation

OpenCode

Connect to https://www.monocrawl.com/mcp with a key from API keys.

Merge this into your active personal configuration, keeping your other servers. Replace mn_your_key_here with your API key locally. Use your profile’s config path if you have a custom profile.

{
  "mcp": {
    "monocrawl": {
      "type": "remote",
      "url": "https://www.monocrawl.com/mcp",
      "headers": {
        "Authorization": "Bearer mn_your_key_here"
      },
      "oauth": false
    }
  }
}

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

{
  "mcp": {
    "monocrawl": {
      "type": "remote",
      "url": "https://www.monocrawl.com/mcp/oauth"
    }
  }
}

Exit the running OpenCode session, then run opencode again to load the saved connection. Then ask: “Check my Monocrawl balance.”

Client documentation

Gemini CLI

Connect to https://www.monocrawl.com/mcp with a key from API keys.

Merge this into your active personal configuration, keeping your other servers. Replace mn_your_key_here with your API key locally. Use your profile’s config path if you have a custom profile.

{
  "mcpServers": {
    "monocrawl": {
      "type": "http",
      "url": "https://www.monocrawl.com/mcp",
      "headers": {
        "Authorization": "Bearer mn_your_key_here"
      }
    }
  }
}

npx -y https://www.monocrawl.com/downloads/monocrawl-cli-1.3.3.tgz init --agent gemini

gemini mcp add --scope user --transport http monocrawl https://www.monocrawl.com/mcp/oauth

/mcp auth monocrawl

In Gemini CLI, run /mcp reload, then /mcp list. Enable Monocrawl if it is disabled and start a new chat if the tools are still missing.

Use Monocrawl’s get_balance tool to check my credits.

Confirm that the reply came from Monocrawl’s tool, not the assistant’s memory. A saved server or a successful sign-in alone does not prove that this chat can call it.

gemini mcp list

gemini mcp remove --scope user monocrawl

Guided setup · Official Gemini CLI documentation

OpenClaw

Connect to https://www.monocrawl.com/mcp with a key from API keys.

Merge this into your active personal configuration, keeping your other servers. Replace mn_your_key_here with your API key locally. Use your profile’s config path if you have a custom profile.

{
  "mcp": {
    "servers": {
      "monocrawl": {
        "transport": "streamable-http",
        "url": "https://www.monocrawl.com/mcp",
        "headers": {
          "Authorization": "Bearer mn_your_key_here"
        }
      }
    }
  }
}

npx -y https://www.monocrawl.com/downloads/monocrawl-cli-1.3.3.tgz init --agent openclaw

openclaw mcp add monocrawl --url https://www.monocrawl.com/mcp/oauth --transport streamable-http --auth oauth

openclaw mcp login monocrawl

Start a new OpenClaw session after setup. If a running Gateway has not loaded the connection, restart it. MCP tools must be enabled in the agent’s tool profile; the minimal profile hides them.

Use Monocrawl’s get_balance tool to check my credits.

Confirm that the reply came from Monocrawl’s tool, not the assistant’s memory. A saved server or a successful sign-in alone does not prove that this chat can call it.

openclaw mcp doctor monocrawl --probe

openclaw mcp logout monocrawl
openclaw mcp unset monocrawl

Guided setup · Official OpenClaw documentation

Hermes

Connect to https://www.monocrawl.com/mcp with a key from API keys.

Merge this into your active personal configuration, keeping your other servers. Replace mn_your_key_here with your API key locally. Use your profile’s config path if you have a custom profile.

mcp_servers:
  monocrawl:
    url: "https://www.monocrawl.com/mcp"
    headers:
      Authorization: "Bearer mn_your_key_here"

npx -y https://www.monocrawl.com/downloads/monocrawl-cli-1.3.3.tgz init --agent hermes

mcp_servers:
  monocrawl:
    url: https://www.monocrawl.com/mcp/oauth
    auth: oauth

hermes mcp login monocrawl

Start a new Hermes chat after sign-in. If tools are missing, check the active profile and that your MCP tool filters allow Monocrawl’s get_balance tool.

Use Monocrawl’s get_balance tool to check my credits.

Confirm that the reply came from Monocrawl’s tool, not the assistant’s memory. A saved server or a successful sign-in alone does not prove that this chat can call it.

Guided setup · Official Hermes documentation

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.

Open Claude.ai · 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.

Open ChatGPT · Client documentation

About the setup command

Requires Node.js 18.17 or newer. The helper installs the connection and skill together, opens Monocrawl in your browser, waits for your approval, saves the credential directly to the selected app and checks account access for free. It works without an interactive terminal and preserves other MCP servers.

Choose claude, codex, cursor, vscode, grok, opencode, gemini, openclaw or hermes with --agent. Use --all only for every detected client. Pass --no-browser to show the approval link without opening it, --oauth for app-managed OAuth, or --skip-auth to install only the OAuth configuration. No API key needs to be copied.

The OpenClaw, Hermes and Gemini CLI commands use our versioned CLI download, so they include the matching adapters. OpenClaw needs a version with its built-in MCP registry.

Client profiles

Run setup on the machine that runs your agent. The helper respects OpenClaw’s OPENCLAW_STATE_DIR and OPENCLAW_CONFIG_PATH, Gemini’s GEMINI_CLI_HOME, and Hermes’s HERMES_HOME or saved active profile. For a non-default profile, set its environment before running the command.

The helper keeps unrelated settings and comments in JSON, JSON5 and YAML. It stops on malformed configuration or a shared YAML MCP mapping instead of replacing it. Workspace trust and tool permissions stay under your control.

Use Monocrawl in your assistant

Start with a balance check, then ask the assistant to discover the relevant endpoints and show the price before retrieving data. For example: “Find the supported Reddit search endpoint and its credit cost. Wait for my approval before searching for mentions of my company.”

For recurring research, ask for a monitor preview first. Review the schedule, estimated credits and budget before creating it. Pause or remove scheduled work in Monitors; disconnecting the assistant does not stop monitors that already exist.

New connections use account billing limits by default. You can add an optional lifetime credit limit in API keys. Existing connection limits remain in place until you change or remove them. Keep the client’s tool-approval controls enabled. A prompt asking for permission is not itself a spending control.

Quick install includes the skill. The alternative native setup does not automatically install it. The Monocrawl skill is available separately; MCP discovery and tool calls work without it.

Verify the connection

Ask your agent: “Check my Monocrawl balance.” Setup is verified only when get_balance succeeds through its MCP tools. This costs no credits. Adding a server or signing in does not prove an already-open chat has loaded it.

Claude Code needs version 2.1.186 or newer for the terminal login command. Older versions can sign in through /mcp. If an existing chat has not loaded the new connection, reconnect it in the client's MCP settings or start a new session.

If Monocrawl already exists, the helper checks and reuses a working saved API key. It updates only that connection. Revoke access and manage its credit limit in API keys. Revoking access does not pause existing monitors.

If Monocrawl specifically reports an invalid or revoked API key, rerun browser setup or replace it in API keys. A generic connection failure may be a network or service problem; inspect the error before changing credentials. In Claude Code, use claude mcp get monocrawl or /mcp.

API-key connections to https://www.monocrawl.com/mcp can use Authorization: Bearer. Existing x-api-key configurations remain supported. Native OAuth and anonymous catalogue discovery are unchanged. Client recovery behavior varies; removing an OAuth header alone does not prevent metadata discovery.

Local MCP package

For clients that launch an MCP process, use Node.js 22 or newer and set MONOCRAWL_API_KEY in the client environment.

npx --yes monocrawl-mcp@latest

The local package uses the hosted server’s current tools and prices. Public discovery requires no key. View package on npm. Client configuration and checksum.

Installable agent skill

npx --yes skills@1.5.26 add https://www.monocrawl.com/agent-onboarding/SKILL.md --agent claude-code --yes

The setup command already installs this file on Node 18.17+. This optional third-party installer needs Node 22.20+. The example installs into Claude Code for the current project without prompts; change --agent to codex, cursor or another supported agent, and add --global for all projects. The direct SKILL.md URL is supported and tested.

n8n

No community node needed — the built-in HTTP Request node is the whole integration:

Download ready-to-import n8n workflows for Google Sheets and Slack →

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.

n8n HTTP Request options

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.