# Using the Lumar MCP Server

https://api-docs.lumar.io/docs/lumar-mcp/usage

# 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.

For a broader catalogue of workflow ideas, see [How to Get Started with the Lumar MCP Server](https://www.lumar.io/blog/company-news/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: 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.
```

## 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.

### 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.
- 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

- [Install the Lumar analytics plugin](./plugins.md).
- [Review authentication and toolsets](./authentication-and-toolsets.md).
- Use the [GraphQL API documentation](../graphql/about-graphql.md) when you need application-level integration instead of conversational MCP access.