What each tool does, what it returns, where the limits are, and what every error means. This is the page your assistant reads when you ask it how bseoa works.
The connector is bseoa as your assistant experiences it: a set of tools it calls directly. There are two ways to run it, and the tools are the same in both.
bseoa mcp runs on your machine, started by Claude Desktop, Claude Code, Cursor, Codex or another desktop host. Crawls run from your machine, with your license, and results are written to the SQLite database at --db-path. JavaScript rendering, semantic analysis, external link checking and CrUX field data are all available. Set up is on the connector page.BlackSEOAnalyzer-Hosted, obeys robots.txt and sends at most two requests a second to a site (how to block it).Results persist in both modes: a crawl you ran yesterday can be read today with list_crawls and the session id it returns.
| Tool | Takes | Returns | Use it when |
|---|---|---|---|
| check_page | url, optional spa (local only) | The page's issues in seconds. Never follows links. | The question is about one page. On hosted it does not count against the page budget. |
| start_crawl | url, optional max_pages (default 500), spa (local only) | A job_id immediately; the crawl continues in the background. | A whole site. Poll crawl_status until it is finished before reading results. |
| crawl_status | job_id | state (queued, running, finished or failed), pages crawled so far, and the session_id once there is one. | Waiting on a crawl. A failed job carries its error. |
| list_crawls | nothing | Every stored crawl session: id, start URL, dates, page count. | Finding "yesterday's crawl". Other tools default to the newest session when none is named. |
| issues_summary | optional session_id | Counts by severity, category and issue key, with example URLs for each key. | Always before query_issues; it is small and shows which keys are worth drilling into. |
| query_issues | optional session_id, min_severity, key, category, url_prefix, offset | Individual issues, at most 100 per call, with next_offset when there are more. | The detail behind a summary line. Filter; do not page through a whole site. |
| page_report | url, optional session_id | Everything recorded about one crawled URL: status, redirect, title, description, headings, counts, timings and its issues. Never the page HTML. | The context behind one page's issues. |
| compare_crawls | base_session, compare_session | Issues that are new, fixed and persisting between the two crawls. | "Did my changes help?" and "what regressed since the deploy?". Only new issues are regressions. |
| serp_preview | urls (at most 50), optional engine (google or bing) | For each URL, how its title and description will look in a search result: length, pixel width, truncation, Open Graph and Twitter Card fallbacks. | Rewriting titles and descriptions. It is about the snippet, not the page's other problems. |
| search_docs | optional query, issue_key, max_results (default 5, at most 10) | Matching sections of this documentation with their URLs, or the reference page for one issue key with its fix. With no arguments, the list of documentation pages. | Any question about bseoa itself. Its answer comes from these pages, not from a web search, and it works offline from a snapshot built into the binary. |
| account_status | nothing (hosted only) | Whether hosted is active, the page budget used and remaining, when it resets, retention, the licenses on the account, and a purchase menu with checkout links. | After a trial_expired, no_hosted_addon or quota_exceeded error, after paying, or to ask what the plan includes. |
max_pages says otherwise. On hosted the hard cap is 2,000 pages per crawl, and a crawl never takes more pages than the account has left in its budget.query_issues returns at most 100 issues per call; follow next_offset for more.serp_preview takes at most 50 URLs per call.check_page, serp_preview, search_docs and account_status are limited to 30 calls a minute per account, and one crawl runs per account at a time; a second start_crawl waits in the queue.Every finding is an issue in the bseoa.issue/v1 shape: a stable key such as metadata.missing_meta_description, a category (the part of the key before the first dot), a severity, the affected url, a human message, a fix_hint and a docs_url pointing at the technical SEO reference page for that key.
Severity is low, medium, high or critical. It ranks the SEO impact of the issue, not how certain the detection is. Group fixes by key, not by URL: one template usually produces hundreds of rows of the same key.
Categories follow the analyzer that found the issue: metadata, content, link, url, performance, web_vitals, mobile, security, structured_data, internationalization, javascript, accessibility, ai_readiness and external_link. The features page describes each analyzer.
To learn what one key means and how to fix it, ask the assistant; it calls search_docs with the issue_key and reads the reference page.
Hosted crawls count pages against a rolling 30-day page budget. check_page, serp_preview and search_docs never count. When the budget is used up, tools answer quota_exceeded with the time it resets, and single-page checks keep working.
Retention counts from the last time a session was read, so a crawl you keep coming back to stays. account_status reports the live numbers for your account and a checkout link for each plan it can buy; the lifetime Single and Agency licenses keep covering everything local.
A tool that cannot do its job returns {"error": "<code>", "message": "..."}, often with an instruction for the assistant and a link. These are the codes.
| Code | Means | What to do |
|---|---|---|
| no_license | Local: bseoa has no active license or the trial ended. | Start the free 14-day trial or buy a license, store the key with bseoa license store <key>, restart the MCP server. |
| trial_expired | Hosted: the trial's hosted access has ended. | Follow the checkout_url in the error for a hosted plan, then call account_status and retry. Local use with a license key is unaffected. |
| no_hosted_addon | Hosted: the account has no hosted plan. | Same as above: the checkout_url is already the right product for the account. |
| quota_exceeded | Hosted: the rolling 30-day page budget is used up. | Wait for resets_at, or keep using check_page, which does not count. |
| rate_limited | Hosted: more than 30 calls a minute to a fetching tool. | Retry after retry_after_seconds. |
| blocked_target | Hosted: the URL points at a private or internal address, or its owner has asked not to be crawled by the hosted connector. | Audit it locally with the bseoa CLI. |
| not_available_hosted | Hosted: spa: true was requested; hosted does not render JavaScript. | Run the crawl locally with --spa, or crawl without rendering. |
| insufficient_scope | Hosted: the connector's token lacks audit:write (for check_page and start_crawl) or audit:read. | Sign in to the connector again and grant the access it asks for. |
| too_many_running_crawls | A crawl is already running for this database (local) or this account (hosted). | Poll crawl_status with the running job's id and start the next crawl when it finishes. |
| invalid_argument | A parameter was out of range: an empty URL list, more than 50 URLs, an unknown severity. | Read the message; it names the limit. |
| unknown_issue_key | search_docs was given an issue_key that bseoa does not emit. | Copy the key field from an issue exactly, including its category prefix. |
| database_error | The crawl database could not be opened or read. | Local: check --db-path is an absolute path the server can write. Hosted: try again shortly; if it persists, write to [email protected]. |
Local: everything is in the SQLite database you name with --db-path. Pass the same absolute path to every host and every CLI command so they read the same crawls. Nothing leaves your machine except the requests the crawler makes to the site being audited and, if you enable them, calls to the AI provider you configured with your own key.
Hosted: one crawl database per account on our servers. Sessions are deleted when their retention has passed since they were last read. Tool results never include page HTML, and hosted stores the page source only for the analysis, never for display.
Ask the assistant in plain words: "does hosted render JavaScript?", "how do I cap a crawl at 200 pages?", "what does link.broken_internal_link mean?". It calls search_docs and answers from these pages with a link.
From a terminal, bseoa docs "how do I crawl from a sitemap" searches the same documentation, bseoa docs --issue <key> fetches one issue's reference page, and --offline uses the snapshot built into the binary.
For your own tooling: /llms.txt indexes the documentation, /llms-full.txt is the full text of the core pages as markdown, and any public page is available as markdown by adding .md to its URL.