# MCP connector

The connector exposes your NessFlow projects to an MCP compatible assistant. It uses the same rights as the public API, for the team chosen when connecting.

## Connect

`https://mcp.nessflow.com/mcp`

- **Claude**: Settings, Connectors, Add custom connector, then paste the address and sign in to NessFlow.
- **ChatGPT**: Settings, Apps and Connectors, Create, then paste the address and sign in to NessFlow.
- **Le Chat**: Intelligence, Connectors, Add connector, Custom MCP, then paste the address.
- **Cursor**: Add the server from the MCP settings, or with the install link in the AI assistant tab of NessFlow.
- **VS Code**: Run “MCP: Add Server”, type HTTP, then the address; or use the NessFlow install link.
- **Claude Code**: One command in the terminal:

## Rights, quotes and log

When connecting, you choose the team and the rights: read, act, spend. Any action that uses the plan first returns a quote with a confirmation handle; the assistant runs it only by sending that handle back. Every action is logged, and the connection can be revoked from NessFlow.

## Tool catalogue

Generated from the server. A connection only sees the tools its rights, plan and modules allow. Descriptions are the ones the assistant receives.

- `nessflow_whoami` (read, Starter): Describe the NessFlow account this connection acts for: the team, its plan, the rights granted to this connection, what it can effectively do once the team settings apply (connection.effective_access, connection.can_spend), the rate limit left, and every plan quota (used, limit, remaining). Use it first, and whenever a refusal mentions a plan limit. A quota limit of null means unlimited; 0 means not included in the plan.
- `nessflow_operations_list` (read, Starter): List what is running right now for the team: crawls in progress (with their stage and their progress as pages crawled out of the page budget), exports, recommendation runs. Use it to know whether a crawl can be launched (one active crawl per team) or to follow a long task. The list is capped; meta.total gives the full count.
- `nessflow_projects_list` (read, Starter): List the projects of the team (one website each), with their identifier, URL and latest completed crawl. Use it to find the project_id other tools need. Paginated: pass meta.next_cursor as cursor for the next page.
- `nessflow_project_get` (read, Starter): Read one project: its website URL, domain, whether it is locked (read only) and its latest completed crawl. Requires the project_id (UUID) returned by the project list.
- `nessflow_project_scorecard_get` (read, Starter): Read the health score of a project and its five pillars (technical, content and AI-answer readiness, accessibility, acquisition, crawlability). A pillar can be not measured: report it as such, never as zero.
- `nessflow_campaigns_list` (read, Starter): List the campaigns of a project: reusable crawl settings (start URL, page budget, schedule). A crawl is always launched from a campaign. Paginated with meta.next_cursor.
- `nessflow_campaign_get` (read, Starter): Read one campaign: its start URL, page budget, crawl options and schedule. Requires the campaign_id (UUID) returned by the campaign list.
- `nessflow_crawls_list` (read, Starter): List the crawls of a project, newest first, with their status and dates. Use it to find the latest finished crawl or a baseline to compare with. Paginated with meta.next_cursor.
- `nessflow_crawl_get` (read, Starter): Read one crawl: status, current stage, pages crawled out of the page budget, dates. A crawl still running is reported as such; read it again later instead of waiting. Requires the crawl_id (UUID).
- `nessflow_issues_list` (read, Starter): List the issue occurrences found by a crawl, one per affected page, filterable by severity, category or exact issue name. Start from the issue summary to pick a name, then list its occurrences. Paginated with meta.next_cursor.
- `nessflow_issues_summary_get` (read, Starter): Summarise the issues of a crawl: totals by severity and one group per issue type with its number of occurrences. Occurrences that only describe a protection page (blocked, challenge) are counted apart, never in the totals.
- `nessflow_pages_list` (read, Starter): List the pages a crawl visited, filterable by HTTP status class and internal or external. Each page carries its URL, status, title and key measures. Paginated with meta.next_cursor.
- `nessflow_page_get` (read, Starter): Read what a crawl measured on one page, given its exact URL: status, title, meta description, H1, word count, canonical, response time, size, links, images and the issues found on it. Use the URL as listed by the page list.
- `nessflow_crawl_pagespeed_get` (read, Starter): Read the PageSpeed results measured during a crawl: the average and the results per page and strategy (mobile, desktop). A strategy that could not be measured is reported as not measured, never as a zero score.
- `nessflow_crawl_geo_get` (read, Starter): Read how readable the website is for AI answer engines (GEO): the score and its axes, AI crawler access, llms.txt, structured data, editorial signals and improvement hints. A score built on few measurable axes says so in its axes.
- `nessflow_crawl_accessibility_get` (read, Starter): Read the accessibility audit of a crawl: score, pages analysed out of the total, failing rules, conformance by principle, contrast pairs, hints and the checks that need a human. Use it to explain which fixes would remove the most violations.
- `nessflow_crawl_eeat_get` (read, Starter): Read the trust foundation report (E-E-A-T) of a crawl: the axes expected for this business, which are present, missing or not measurable, and the evidence pages.
- `nessflow_crawl_structure_get` (read, Starter): Read the internal linking structure of a crawl: depth from the home page, orphan pages, pages with few inbound links, and link scores (ranks, not grades). A truncated crawl reports its figures as not comparable.
- `nessflow_crawls_compare` (read, Starter): Compare a crawl with a baseline crawl of the same project (baseline is a crawl UUID): the summary of changes, status codes, issues and pages that appeared, disappeared or changed. Pick the baseline from the crawl list.
- `nessflow_recommendations_get` (read, Starter): Read the AI recommendations of a project: global actions ranked by impact and effort, with the signals they come from, and per-page actions. Generated from the latest audits; reading them costs nothing.
- `nessflow_export_get` (read, Starter): Read the state of an export (Excel or PDF): pending, ready or expired. When ready, it carries the download address on the NessFlow API, which needs an API token: tell the user to download the file from the exports of the NessFlow app rather than fetching it.
- `nessflow_positions_get` (read, Starter): Read the rank tracking of a project over a period: tracked keywords, their positions and trend. Not in the top 100 is a measured fact; a keyword not yet checked is not measured. Rankings carry a trend, never a score.
- `nessflow_search_console_get` (read, Starter): Read the Search Console data of a project over a period: performance (clicks, impressions, average position) and indexation. Requires the project to have connected its Search Console property.
- `nessflow_backlinks_get` (read, Pro): Read the latest backlink profile snapshot of a project, for the target it was measured on. Available when the backlink module is active for the project.
- `nessflow_security_get` (read, Starter): Read the latest passive security scan of a project: score, counts by severity and findings. Passive detection only: nothing is scanned for vulnerabilities or attacked.
- `nessflow_logs_get` (read, Starter): Read the server log analysis of a project over a period: totals and daily series of crawler visits, and the days missing from the collection. No IP address is ever returned.
- `nessflow_project_create` (write, Pro): Create a project for a website the team wants to audit. It uses one project slot of the plan, so the first call returns a quote; call again with the confirmation to create it. The new project still needs a campaign before a crawl can run.
- `nessflow_project_update` (destructive, Pro): Rename a project or change its website URL. Changing the URL erases what described the previous site (profile, priority URLs), so the first call returns a quote and nothing changes until it is confirmed.
- `nessflow_campaign_create` (write, Pro): Create a campaign on a project: the start URL, the page budget, the crawl depth and the options (JavaScript rendering, PageSpeed, accessibility, external links) a crawl will use, and an optional schedule. Credentials for a protected site are set on the NessFlow screen, never here.
- `nessflow_campaign_update` (write, Pro): Change the settings or the schedule of a campaign. The next crawl uses the new settings; past crawls keep theirs. Credentials for a protected site are set on the NessFlow screen, never here.
- `nessflow_campaign_delete` (destructive, Pro): Delete a campaign, stopping its crawl if one is running. This cannot be undone, so the first call returns a quote; call again with the confirmation to delete. An assistant can delete a few campaigns per day at most.
- `nessflow_crawl_launch` (billed, Pro): Launch a crawl of a campaign. It fetches the website and uses the plan, so the first call returns a quote; call again with the confirmation to launch. One crawl runs at a time per team. Returns at once with the crawl identifier; read its state again later.
- `nessflow_crawl_stop` (write, Pro): Stop a running crawl now. What was already crawled is kept and marked as truncated, so it is not compared with complete crawls. Stopping is never refused for billing reasons.
- `nessflow_recommendations_generate` (billed, Pro): Generate new AI recommendations for a project from its latest audits. It uses one generation of the monthly allowance, so the first call returns a quote; call again with the confirmation. Runs in the background: read the recommendations again later.
- `nessflow_export_create` (write, Pro): Request a full export of a finished crawl, as an Excel workbook or a PDF report. Runs in the background and returns the export identifier; read the export again later to get its download link.
- `nessflow_keywords_track` (billed, Pro): Start tracking keywords for a project: their position will be checked every day. Each keyword uses one slot of the plan, so the first call returns a quote; call again with the confirmation.
- `nessflow_keywords_untrack` (write, Pro): Stop tracking keywords for a project and free their slots. Their history is kept. Freeing slots is never refused for billing reasons.
- `nessflow_keywords_pause` (write, Pro): Pause the daily check of tracked keywords and free their slots, keeping them in the list and their history. Resuming them later uses slots again.
- `nessflow_keywords_resume` (billed, Pro): Resume the daily check of paused keywords. Each keyword uses one slot of the plan again, so the first call returns a quote; call again with the confirmation.
- `nessflow_keyword_check_now` (billed, Pro): Check the position of one tracked keyword now instead of waiting for the daily check. It uses one live check of the daily allowance, so the first call returns a quote; call again with the confirmation. The result arrives in the background.

## Examples

- **Understand what changed since the last audit**: Compare the latest audit of {project} with the previous one. Separate real regressions, noise, and what you cannot decide for lack of measurement. For each real regression, give the most affected page.
- **Prepare the client report**: Prepare the monthly report of {project} for my client: what improved, what regressed, what cannot be measured yet. Ten lines at most, every figure with its denominator.
- **Prioritise fixes**: Which ten fixes would raise the health score of {project} the most for the least effort? For each: the pillar it touches, the number of pages, and an example URL.
- **Check that a fix worked**: I fixed the title tags of the product pages. Run the audit of {campaign} again, tell me first what it will use, then remind me when we can conclude whether the fix worked.
- **Find orphan pages that get traffic**: Which pages of {project} are orphans or more than four clicks from the home page, and which of them still get Search Console traffic?
- **Build this month’s action plan**: Build the SEO action plan of {project} for this month from its recommendations: three workstreams at most, ranked by impact and effort, with the health score pillar each one improves.
- **Know which AI crawlers can read the site**: Which AI answer engine crawlers are allowed to read {project}, which are blocked, and is the rule blocking them intended or accidental?
- **Measure readability by AI engines**: Is my website readable by AI answer engines? Give the GEO score of {project}, the three main blockers, and the most exemplary page to imitate.
- **Review the portfolio**: Go through all my projects: which one dropped the most since its last audit, and why? Ignore those whose audit is too recent to conclude.

## Connector specific errors

- `confirmation.invalid`: Unknown or expired confirmation, or one issued to another connection: ask for a new quote.
- `confirmation.mismatch`: This confirmation was issued for other arguments: ask for a new quote.
- `mcp.spend_not_granted`: This connection was not granted the right to use your plan's quotas.
- `mcp.destructive_cap`: Daily limit of deletions by an assistant reached.
- `mcp.disabled_by_team`: Your team has closed the connector to assistants.
- `mcp.client_not_allowed`: Your team does not allow this assistant.
- `mcp.input_not_available`: This setting cannot be changed by an assistant: set it in NessFlow.
- `mcp.pkce_required`: This authorization request requires PKCE with the S256 method.