Crawle
Log inStart monitoring

API and MCP setup

Connect Crawle to an AI assistant with MCP, or to your own scripts with an API key.

On this page

Choose how to connect

MCP with OAuth

Use it when
A person connects Crawle to an AI assistant or agent platform.
Sign-in
OAuth: the person approves the scopes.
Access
Read. Write tools are in preview and also need the person's workspace role.
Workspaces
Every workspace the person can open, one at a time.

API key

Use it when
A server-side script, scheduled job or integration runs without an interactive user.
Sign-in
A key created in the app under Settings › API keys.
Access
Read only.
Workspaces
The one workspace the key belongs to.

Connect Crawle to your AI assistant

  1. Step 1: Add the connector

    Add Crawle as a remote MCP connector in your agent platform, with this server URL.

    URL
    https://api.crawle.io/mcp

  2. Step 2: Sign in with OAuth

    Authenticate with OAuth when the agent platform asks to connect Crawle.

  3. Step 3: Approve only the scopes you need

    Reconnect the connector after scope changes, so the agent receives the updated grant.

    Scopes →

  4. Step 4: Try a first prompt

    Ask the agent to list your workspaces before it inspects sites. The connected app then shows in Crawle under Settings › Connected apps.

Scopes

A tool needs one scope. Approve the read scopes for questions; add a write scope only when the agent should change something.

Read

  • sites:read

    Gives access to
    AI readiness, account context, client groups, crawl exclusion rules, effective settings, google, migrations, overview, regions, sitemaps, sites, tags, verification, weekly report settings, weekly reports, workspaces
    Example tool
    list_ai_bot_access

  • urls:read

    Gives access to
    URLs, google, segments
    Example tool
    list_segments

  • issues:read

    Gives access to
    issues, redirect chains
    Example tool
    list_issues

  • alerts:read

    Gives access to
    alert trigger configs, alerts, custom extractions, incidents, notification settings
    Example tool
    list_alert_trigger_configs

  • changes:read

    Gives access to
    URLs, changes
    Example tool
    list_recent_changes

  • links:read

    Gives access to
    internal link score, links
    Example tool
    list_links

  • exports:read

    Gives access to
    exports
    Example tool
    list_exports

  • historical:read

    Gives access to
    GSC, historical
    Example tool
    list_gsc_query_metrics

  • technology:read

    Gives access to
    technology
    Example tool
    list_technology_findings

  • workspaces:read

    Gives access to
    workspaces
    Example tool
    list_workspaces

  • account:read

    Gives access to
    account context
    Example tool
    get_workspace_context

Write

OAuth only, and the person's role must allow the change.

  • sites:write

    Gives access to
    AI readiness, URL submissions, URLs, delete preview, migrations, segments, sitemaps, sites, verification
    Example tool
    create_segment

  • settings:write

    Gives access to
    bulk settings
    Example tool
    apply_bulk_settings

  • alerts:write

    Gives access to
    alert policy, alert trigger configs, custom extractions, notification settings
    Example tool
    create_alert_trigger_override

  • exports:write

    Gives access to
    exports
    Example tool
    create_export

  • workspace:write

    Gives access to
    client groups, tags
    Example tool
    create_client_group

  • team:write

    Gives access to
    team
    Example tool
    update_team_member_role

  • technology:write

    Gives access to
    technology
    Example tool
    update_site_technology_settings

Workspace context

Workspace context is explicit, so agencies can use one account across multiple client workspaces without leaking data between them.

Example prompts

MCP works best when the request is specific about workspace, site, severity, time window, and desired output.

  • “List critical issues for example.com and group them by template or URL pattern.”

    Reads the site's issues with list_issues (issues:read).

  • “Find broken internal links, include source pages, and suggest which links should be updated first.”

    Reads links with list_links (links:read).

  • “Summarize what changed on this site during the last 24 hours and separate open from resolved incidents.”

    Reads changes and incidents with list_recent_changes and list_incidents (changes:read, alerts:read).

  • “Check the detected technology stack for this site and summarize any high-confidence exposed-version risks.”

    Reads the stack with get_site_technology_stack (technology:read).

What the agent gets back

For the incidents prompt, the tool's REST equivalent GET /v1/api/sites/{site_id}/incidents returns this shape:

ResponseJSON
{
  "items": [
    {
      "acknowledged_at": "example",
      "acknowledged_by": "example",
      "affected_count": 1,
      "closure_kind": "merged_into_group",
      "created_at": "example",
      "details": {},
      "eligibility_revision": 1,
      "escalation_count": 1,
      "extra_data": {
        "closure_kind": "consumed"
      },
      "first_detected_at": "example",
      "id": 1,
      "last_checked_at": "example",
      "membership_key": "example",
      "membership_revision": "example",
      "membership_state": "confirmed",
      "redirected_count": 1,
      "resolved_at": "example",
      "resolved_count": 1,
      "restored_count": 1,
      "severity": "critical",
      "status": "active",
      "summary": "example",
      "title": "Example",
      "trigger_type": "example",
      "website_id": 1
    }
  ],
  "limit": 1,
  "next_cursor": "example",
  "offset": 1,
  "resolve_selection_count": 1,
  "resolve_selection_filter_summary": {},
  "resolve_selection_skipped_count": 1,
  "resolve_selection_token": "example",
  "selection_count": 1,
  "selection_filter_summary": {},
  "selection_token": "example",
  "sort_by": "example",
  "total": 1,
  "unclassified_count": 1
}

API keys for scripts

API keys are still useful for server-side scripts, scheduled jobs, and integrations that do not involve an interactive user. Grant the narrowest scopes needed and rotate keys when teammates, vendors, or automation ownership changes.

Last updated October 29, 2026