Skip to main content

Using the Lumar MCP Server

You do not need to memorize MCP tool names. Start with the business outcome, identify the Lumar account/project/crawl, and tell the assistant whether it may perform actions or should only analyze.

On Native V1, the client sees each granted operation as a tool. On the opt-in Compact V2 beta, the client sees three tools and uses lumar_find to discover the same operations on demand. See Native and Compact Tool Surfaces.

For a broader catalogue of workflow ideas, see How to Get Started with the Lumar MCP Server. This page focuses on behavior that matters when operating the MCP tools.

A reliable prompt structure​

Include:

  1. Scope -- account, project, URL, or AI Visibility brand.
  2. Time or crawl -- latest completed crawl, a named crawl, or a date range.
  3. Question -- the comparison, diagnosis, or data you need.
  4. Output -- table, prioritized list, executive summary, or export.
  5. Action boundary -- read-only, prepare a proposed change, or perform the change after confirmation.

For example:

Using the latest completed crawl for <project>, identify the three report categories
that worsened most. Show the affected URL count, likely impact, and a short remediation plan.
Do not create tasks yet.

Example: Analyze a crawl​

Audit the latest completed crawl for <project>. Summarize health, rank the largest issues,
and compare them with the previous crawl.

Example: Preview a segment​

Using the latest completed crawl for <project>, preview a segment of URLs under /blog/
with HTTP status 200. Show how many URLs match before saving the segment.

analyze_preview_segment requires analyze:read and a crawlId. Pass the proposed filterRules and optional filterOperator (AND by default), or a raw nested filter. Both forms accept at most 20 predicates per preview. Segment writes can accept larger raw filters, but those cannot be previewed in one call. The result includes matchingUrlCount, crawlId, and projectId; zero means no URLs matched. If crawl URL data is unavailable, the tool returns an error instead of a zero count. Accessibility and SiteSpeed previews accept only URL, discovery-source, custom-extraction, and custom-metric fields joined with AND/OR groups, matching their segment write restrictions.

The preview uses the selected crawl's all_pages report and does not save a segment or start a crawl. Refine the criteria and preview again as needed, then use analyze_create_segment or analyze_update_segment with analyze:write to save them. Future crawl counts can differ, and a successful preview does not validate write permissions or segment quotas.

Example: Check a crawl schedule​

Check the schedule history for <project>. Explain why the expected crawl did not
start, and show any crawl activity around that time.

With analyze:read, analyze_list_schedule_logs accepts a projectId from analyze_list_projects and returns the current schedule plus project logs newest first. Each log includes createdAt, errorCode, and errorMessage. Use limit (default 20, maximum 100) and pass pagination.next_cursor as cursor for older entries.

Schedule logs have a six-month retention window, with older entries removed by daily cleanup. Pagination cannot recover expired history; missing logs for an older period do not mean there were no failures.

These logs record failed or skipped scheduled crawl starts, such as depleted credits or a crawl already running. Successful starts and crawl completion are not recorded in this log, so an empty result does not prove success. A new schedule initializes latestRunTime to the same future first-run time as nextRunTime, before any attempt; later, latestRunTime also advances for handled failures. Compare these timestamps with the current time, logs, and crawl history before treating them as evidence of a past occurrence. nextRunTime and the recurrence describe future scheduling. Logs can remain when the current schedule is null, including after deletion or a one-time schedule has been consumed.

Use analyze_list_crawls and analyze_get_crawl_summary to inspect crawl activity and outcomes around the expected time. A crawl starting nearby in time does not by itself prove it was scheduled.

Example: Configure sitemap crawling​

List the sitemaps configured for <project>, including disabled entries.
Add https://www.example.com/sitemap.xml and enable the Sitemap crawl source,
preserving the project's other sources. Show the resulting configuration.

analyze_list_sitemaps requires analyze:read and returns URL, urlDigest, enabled state, type, status, and available hierarchy metadata. Follow pagination.next_cursor for more results. These are project settings; status indicates URL validity, not the outcome of a crawl.

With analyze:admin and Editor access, use analyze_add_custom_sitemaps to add 1–50 HTTP(S) URLs at a time. Existing entries are preserved and duplicates are ignored; adding a disabled URL does not re-enable it. Use analyze_enable_sitemap, analyze_disable_sitemap, or analyze_delete_sitemap with the project's ID and a urlDigest returned by the list tool. Enable and disable also apply to any child sitemaps.

Deleting clears the URL's disabled state as well as removing it. If robots.txt still advertises that URL and discovery is enabled, it can be rediscovered immediately; the result then reports deleted: false. Disable the sitemap to keep it excluded. Listing includes discovered robots.txt URLs without saving them to project settings.

Mutations return summaries. Re-list from the first page to verify changes. Managing sitemap URLs does not enable the Sitemap crawl source: read analyze_get_project_settings and use analyze_update_project to include Sitemap in crawlTypes, preserving existing sources. Changes apply to future crawls, and sitemap mutations fail while a crawl is running.

Example: Configure log or Adobe Analytics sources​

For <project>, inspect the current log and analytics sources. Use my working
Splunk connection to configure the agreed log query, preserving other sources.
Show the saved query and whether its URLs are crawled or imported as data only.

Use an interactive user session with analyze:read, analyze:external, and analyze:admin. The bundled analyze-source-integrations skill covers the read, configure, and verify workflow.

  • Discover working connections with analyze_list_logzio_connections, analyze_list_splunk_connections, or analyze_list_adobe_connections. These tools check the provider and return paginated results without secrets.
  • For Logz.io/Splunk, list the project's existing queries before using the matching analyze_create_*_project_query or analyze_update_*_project_query tool. Connection create/update tools accept credentials and validate them with the provider. Logz.io detects the token's region automatically; Splunk supports HTTP(S)/SOCKS proxies and pairs the proxy URL with its mode.
  • Logz.io logFilters are bounded ANDed conditions with term, match, or regexp, and optional exclusions. Supplying filters replaces the existing filter; null or [] clears it. Omission preserves advanced filters saved in Analyze. Splunk takes a search expression without the initial search command. When supplying splunkConnectionId on an update, also supply the query so it is validated against that connection.
  • For Adobe, pass a working connection's opaque nodeId to analyze_list_adobe_report_suites and analyze_list_adobe_url_dimensions. Bind the chosen suite and URL dimension with analyze_create_adobe_integration, or patch the existing binding with analyze_update_adobe_integration. Updates that change the suite or Adobe connection supply the report suite ID, its matching name, and URL dimension together; the suite name cannot be changed independently. Dimension IDs omit variables/. Creating Adobe credentials remains an Analyze app step.

Numeric IDs from discovery identify connections, queries, and bindings. Follow pagination.next_cursor on lists. Updates preserve omitted values. Project mutations require Editor access and fail while a crawl is running.

Saving or enabling an integration does not activate its shared crawl source. Read analyze_get_project_settings, then use analyze_update_project to add LogSummary for logs or GoogleAnalytics for Adobe to crawlTypes, preserving other entries. For data-only imports also include that source in dataOnlyCrawlTypes and retain another URL crawl source. Re-read both settings and the saved integration to verify the requested configuration.

Deleting a Logz.io/Splunk connection disables its queries across every project using it. Deleting a project query or Adobe binding preserves historical crawl data and leaves shared source flags unchanged. Keep those flags while another integration or upload still depends on them. Service accounts can read/delete project queries and Adobe bindings, but connection-dependent setup requires a user.

Example: Review AI Visibility​

Compare our AI Visibility over the last 30 days with the preceding 30 days.
Break the movement down by topic and provider, then flag new competitors.

Save a custom Analyze report​

For <project>, preview a report of pages with HTTP status 404, showing URL and status.
Show me the proposed filter and columns before saving it as "Broken pages" for the team.

With analyze:read and analyze:write granted, the assistant can discover existing custom reports, preview a definition, and save it with analyze_create_custom_report_template. A custom report uses a standard base report plus a required filter, with optional column groups, sort, description, and Table/Grid preference.

Use analyze_update_custom_report_template to change a saved report. Omitted settings stay unchanged; supplied filters, column groups, and sort replace the complete saved values. A null column grouping or sort restores the base report's defaults. The base report is fixed at creation. Reports supplied by custom metric extensions can be copied into a project report, but cannot be edited or deleted with these tools.

analyze_delete_custom_report_template also removes the report's associated Monitor alert rules. Review that consequence before confirming deletion. Templates tied to remediation tasks are protected by the API, and MCP provides no restore tool.

Create, update, and delete take numeric project/template IDs. The existing detail tool reads by project ID and template code; the custom-report row tool reads by numeric template ID. Custom report codes cannot be used as standard report codes.

Example: Upload a URL list for a crawl​

Upload urls.txt to <project>, wait for processing, and enable the List crawl
source while preserving the other sources. Show the file status and row count.

With analyze:read, use analyze_get_url_file_upload_types to discover supported URL list, backlink CSV and log-summary CSV formats and their column templates. Log files must be summary CSVs rather than raw server logs. ListTxt takes one URL per line without a header. analyze_list_url_file_uploads returns existing files, including disabled entries; follow pagination.next_cursor for more. Keep each returned opaque upload ID unchanged.

With analyze:admin and Editor access, call analyze_create_signed_url_file_upload with the project, file basename and projectUploadType. The crawl source is derived from the format. This creates a Draft record and a signed URL; it does not transfer file bytes. The caller must send the raw file bytes with HTTP PUT to upload.url within 15 minutes, without multipart encoding or the Lumar authorization header. If the client cannot perform that transfer, complete the upload in Analyze. Each creation makes a new record, so inspect existing files before retrying an uncertain call.

Poll analyze_get_url_file_upload with urlFileUploadId until Processed. Draft awaits transfer, Processing is pending, and Errored includes an error message. The file is ready for crawling only after processing succeeds. Enable its List, Backlinks or LogSummary source separately using analyze_update_project, preserving the project's other sources.

analyze_update_url_file_upload changes enabled state, base domain (null clears it), or a built-in format within the same crawl source. Omitted settings are preserved. To replace file contents, create a new upload and wait for processing before disabling or deleting the old one. analyze_delete_url_file_upload removes a file; disabling retains it for reuse. Upload mutations require that no crawl is running. Custom column templates are not writable through MCP.

Operating behavior​

Choose a completed crawl​

Results come from live Lumar data. A crawl that is still running may have incomplete report or segment results. Ask for the latest completed crawl unless investigating progress.

Resolve ambiguous resources​

If several accounts or projects match, the assistant should show candidates rather than guessing. Use the full project name or domain when possible.

Narrow large requests​

Report rows and other list tools are paginated and protected by a response-size budget. Narrow by report, segment, filters, metrics, or date before asking for every row. Use a report export when the complete dataset is the actual deliverable.

Treat long operations as asynchronous​

Crawls, exports, custom-metric generation, and some AI Visibility runs do not finish in one MCP call. Keep the returned ID, check status later, and avoid asking the assistant to poll continuously.

Review write actions​

Creating projects, running crawls, changing segments, linking Jira issues, and deleting resources can alter Lumar or an external system. Review the proposed scope and parameters before confirming.

Project creation and project-wide settings require analyze:admin. Jira operations require analyze:external, and some Jira/task actions require an interactive user rather than a service account.

Adjust report scoring​

Use analyze_list_report_template_overrides (analyze:read) to inspect a project's report adjustments. Filter by reportTemplateCode to inspect one report, and follow pagination.next_cursor while has_next_page is true.

With analyze:write and an Editor or Admin role on the project’s account, use analyze_create_report_template_override, analyze_update_report_template_override, or analyze_delete_report_template_override. Each adjustment is identified by projectId, reportTemplateCode, and aggregateCode. Omit aggregateCode or pass null for a report-total adjustment; keep a returned aggregate code when changing an aggregate adjustment.

  • totalSign sets impact: -1 negative, 0 neutral, 1 positive.
  • totalWeight sets scoring weight from 0 to 1; 0 removes scoring impact.
  • Creation requires both values and is subject to the account's override limit.
  • Updates preserve omitted values and require at least one scoring value.
  • Deletion restores template defaults. Its response contains the removed values.

Changes apply to future crawls and do not start a crawl or recalculate existing results. Report-total adjustments also change any linked health-score parent override. Read the current adjustments before writing, and verify the saved values afterward (or list again after deletion).

The same account and role checks apply to the GraphQL mutations createReportTemplateOverride, updateReportTemplateOverride, and deleteReportTemplateOverride. Service accounts can only adjust projects in their own account; Viewer and Reporter roles can read overrides but cannot change them.

Numeric report thresholds, such as title-length limits, are separate settings. Read them with analyze_get_project_settings using sections: ["thresholds"] and change them through analyze_update_project with analyze:admin.

Check quota before expensive work​

Use the always-on account-credit tool before starting a crawl or bulk AI Visibility run. Per-crawl credit consumption remains available in the Lumar dashboard.

Prefer inline retrieval over signed files​

The Analyze tools can return stored crawl HTML and named Single Page Requester outputs inline. Use those tools when an MCP client cannot open a presigned download URL.

Troubleshooting​

Lumar tools do not appear​

  • Confirm the URL is exactly https://mcp.lumar.io/mcp.
  • Complete the Lumar login and consent flow.
  • Restart or reconnect the AI client if it does not refresh tool discovery.
  • Confirm which tool surface was selected. Seeing only lumar_find, lumar_read, and lumar_act is expected on Compact V2.
  • Check whether the required toolset was selected.
  • For project lifecycle tools, grant analyze:admin.

Authentication fails​

  • Reconnect to refresh an expired OAuth session.
  • Confirm an active account has the MCP Server addon.
  • For a user/service-account key, verify the full credential, expiration, and revocation status.
  • For a service account with an IP allowlist, remember that the hosted MCP's egress IP is evaluated.

A project cannot be found​

Ask the assistant to list accessible accounts and projects first. Then retry with the exact project name, domain, or numeric ID.

A service-account tool is missing​

The operation may be user-bound. Task creation, AI ticket generation, Jira link creation, custom-metric LLM generation requests, and Google connection discovery require an interactive user session.

Responses are slow or too large​

Large report reads, exports, and trend analysis may take longer. Apply narrower filters or request fewer fields. For exports and other asynchronous jobs, ask for status later using the returned ID.

Next steps​