User guide10 min

Connect your AI assistant with MCP

Connect your AI assistant to PixyScan once, and it can answer questions about your sites from your real scan results: what is wrong, which pages are affected, and the fix guide for each problem. You sign in through your browser, so there is no key or password to paste. It takes about five minutes.

Before you start#

Check these four things first. Each one is a common reason the assistant cannot see your sites.

You need	Where to check	What it does
A Basic, Pro or Enterprise plan	Billing	The assistant can only read sites in workspaces on Basic or above. Workspaces on Free or Hobby are skipped, and the assistant tells you so. See Billing.
A Google account with your PixyScan email	Your account	Assistants sign in to PixyScan with Google. Use the Google account whose email address is the one you use for PixyScan. Any other Google account signs in to a new, empty PixyScan account instead of yours.
At least one finished scan	Scan history	The assistant reads a site's latest finished scan. A site that has never been scanned has nothing to read yet. See Run a scan.
An assistant that supports MCP	Your assistant	This page has steps for Claude (the desktop app, claude.ai and Claude Code), Cursor and VS Code. Most other assistants can connect too: see Any other assistant.

How it works, in plain words. MCP, short for Model Context Protocol, is the standard way AI assistants plug into other tools. PixyScan runs an MCP server at one web address. You give your assistant that address once. The first time it connects, a browser window opens and you sign in. After that, when you ask about your site, the assistant asks PixyScan for the facts and answers from them, instead of guessing.

The assistant sees what you can see in PixyScan, and nothing more: the workspaces you belong to and the sites you have access to. It can read results and add a new site. It cannot start a scan, change a setting or delete anything, and nothing in PixyScan edits your website.

Server address: https://mcp.app.pixyscan.com/mcp
Sign-in: With Google, in your browser
Plan: Basic, Pro or Enterprise
Uses: No URL credits

Step 1: Copy the server address#

Every assistant needs the same one thing: this address.

PixyScan MCP server

https://mcp.app.pixyscan.com/mcp

It is a remote server, so there is nothing to install or keep running on your computer. There is no API key or token to create either. When your assistant first connects, it opens a browser window and you sign in there.

Then follow step 2 for your assistant. You only need one: Claude desktop app and claude.ai, Claude Code, Cursor, VS Code or any other assistant.

Step 2: Claude desktop app and claude.ai#

In Claude, PixyScan is added as a custom connector.

1
Open Settings, then Connectors
In the Claude desktop app or at claude.ai, open Settings from the menu under your name, then choose Connectors.
2
Press Add custom connector
Type PixyScan as the name, and paste the server address from step 1 as the URL. Press Add.
3
Press Connect and sign in
A browser window opens on a PixyScan page that says Connecting your PixyScan account, then moves on to Google. Choose the Google account with your PixyScan email and approve. The window then sends you back to Claude, and PixyScan shows as connected.
4
Check PixyScan is on in your chat
Start a new chat and open the tools menu in the message box. Make sure PixyScan is switched on, then ask a question. See What you can ask.

On a Claude Team or Enterprise plan

An owner of your Claude organisation may need to add the connector for everyone first. After that, each person presses Connect and signs in with their own Google account.

Step 2: Claude Code#

In Claude Code, PixyScan is added as a remote MCP server.

1
Add the server
Add PixyScan to Claude Code as an HTTP MCP server named pixyscan, with the server address from step 1. You can add it to one project or to every project. Claude Code's own help shows where.
2
Sign in
Start Claude Code and open its MCP servers list. Choose pixyscan, then Authenticate. Your browser opens. Choose the Google account with your PixyScan email and approve, then go back to the terminal.
3
Ask a question
For example: Using PixyScan, what should I fix first on example.com? The first time it uses a PixyScan tool, Claude Code asks for your permission. Allow it.

Step 2: Cursor#

In Cursor, PixyScan is added to a settings file called mcp.json.

1
Open mcp.json
Open Cursor Settings, find the MCP section, and press the button to add a new MCP server. Cursor opens the file for you.
You can also create the file yourself: ~/.cursor/mcp.json in your home folder works in every project, and .cursor/mcp.json inside a project works in that project only.
2
Paste in the PixyScan server
Copy the text below into the file and save it. If the file already lists other servers, add the pixyscan entry inside the existing mcpServers.
~/.cursor/mcp.json
```
{
  "mcpServers": {
    "pixyscan": {
      "url": "https://mcp.app.pixyscan.com/mcp"
    }
  }
}
```
3
Sign in
Go back to the MCP section of Cursor Settings. PixyScan is listed and asks you to sign in. Press the sign-in button beside it, then choose the Google account with your PixyScan email and approve in your browser.
4
Ask in Agent mode
Open the chat, make sure it is in Agent mode, and ask your question.

Step 2: VS Code with GitHub Copilot#

In VS Code, PixyScan is added to a file called mcp.json in your project, and used from Copilot Chat in Agent mode.

1
Create .vscode/mcp.json
In your project, create a folder called .vscode if there is not one, and a file inside it called mcp.json. Copy the text below into it and save.
Or open the Command Palette, run MCP: Add Server, choose HTTP, and paste the server address from step 1. VS Code writes the file for you.
.vscode/mcp.json
```
{
  "servers": {
    "pixyscan": {
      "type": "http",
      "url": "https://mcp.app.pixyscan.com/mcp"
    }
  }
}
```
2
Start the server and sign in
In the file, press Start just above pixyscan. VS Code asks whether PixyScan may sign in: allow it, then choose the Google account with your PixyScan email and approve in your browser.
3
Ask in Agent mode
Open Copilot Chat, switch the mode to Agent, and ask your question. VS Code may ask you to confirm before it uses a PixyScan tool.

Step 2: Any other assistant#

Most assistants that support MCP can connect to a remote server.

Look in its settings for MCP, Connectors or Tools, and paste the server address from step 1. When it asks how to sign in, choose OAuth or browser sign-in, not an API key. PixyScan works with assistants that support remote servers over HTTP (sometimes called Streamable HTTP) with OAuth sign-in.

Step 3: Ask in plain words#

Name the site by its name or its address. The assistant chooses the right PixyScan tool by itself.

You ask	It uses	What it does
Which sites do I have in PixyScan?	list_workspaces, list_sites	Lists your workspaces, your role in each, and the sites in them.
What should I fix first on example.com?	get_site_issues	Reads the latest finished scan and lists its problems, most serious first, each with a few example pages.
Show me only the critical issues on example.com.	get_site_issues	The same list, cut down to one severity: Critical, Important or Standard.
Which pages have broken internal links?	get_issue_details	Every page one problem affects, grouped by the section of the site they are in, so a fault in one template shows up as one group.
How do I fix pages with no canonical tag?	get_issue_guide	The fix guide for that check, the same one the app shows: what it is, why it matters, how to fix it, and examples.
Fix the missing canonical tags in this project.	Several	In a coding assistant such as Claude Code, Cursor or VS Code, it reads the problem, the affected pages and the fix guide, then changes your code. Check its changes before you merge them.
Add a site called Blog for https://blog.example.com.	create_site	Adds the site to the workspace you name. Start its first scan in the app.

Answers come from the latest scan that has finished. After you fix something, the answer changes only once a new scan has run, from the app, your schedule or your pipeline.

A coding assistant that can run terminal commands can also check its own fix. Once the fix is deployed, for example to your staging address, ask it to run the PixyScan check from Connect your CI/CD pipeline. The scan passes your score gate or it does not.

All nine tools. You never have to name them, but your assistant may show them when it asks for permission.
Tool	Reads or changes	What it does
list_workspaces	Reads	Your workspaces, and your role in each.
list_sites	Reads	The sites in one workspace.
find_site	Reads	Finds a site from a name, a domain or an address.
get_site_issues	Reads	A site's problems from its latest finished scan, most serious first, up to 200 at a time.
get_issue_details	Reads	The pages one problem affects, grouped by section of the site.
get_issue_guide	Reads	The fix guide for one check.
list_issue_checks	Reads	Every check PixyScan runs, which can be filtered by severity or category.
get_user_info	Reads	Your name and email address, so the assistant knows who is signed in.
create_site	Changes	Adds a new site to a workspace. The only tool that changes anything.

What the assistant cannot do#

Knowing these saves you asking for something it cannot give.

It cannot	Instead	What it does
Start a scan	The app or your pipeline	Press Scan now in the app, use a schedule, or scan from your pipeline. The assistant reads the result once it finishes.
Change settings or delete anything	The app	Every setting, member and site is changed in PixyScan itself.
Read Search Console figures	Search performance	Clicks, impressions and Search impact are only in the app. See Search Console.
Add a site as a Viewer	Ask an admin	Adding a site needs the Member role or higher, and counts towards your plan's site limit. The address must start with https://.
Read workspaces on Free or Hobby	Billing	Those workspaces are skipped. Your workspaces on Basic or above still work.

Using the assistant costs no URL credits, because it only reads results. The Billing view counts MCP calls under usage. They are counted, not charged.

Staying signed in, and disconnecting#

What to expect after the first sign-in.

Signing in again. For your security, a sign-in from an assistant lasts a short time, not days. When it runs out, the assistant asks you to sign in again, or reports that it is not authorised. Sign in again the same way. Nothing else needs setting up.

Your other sessions. Each sign-in from an assistant counts as one signed-in session, like a browser. If you have many sessions at once, PixyScan signs out the oldest one.

Disconnecting. Remove PixyScan from your assistant: delete the connector in Claude, remove the pixyscan server in Claude Code, or delete the pixyscan entry from the mcp.json file. The assistant can then no longer reach PixyScan.

Cutting off access at once, everywhere. If a device with a connected assistant is lost, reset your PixyScan password. A password reset signs you out of PixyScan everywhere, every assistant included.

Troubleshooting#

Find what your assistant says, then do what the last column says.

The assistant says	Cause	What it does
MCP access requires a Basic plan or above.	Plan	The workspace is on Free or Hobby. Move it to Basic or above on Billing.
… workspace(s) were not searched because their plan does not include MCP access	Plan	Those workspaces are on Free or Hobby. Sites in your other workspaces were still searched.
No pixyscan sites are available to this account.	Wrong Google account	You probably signed in with a Google account that is not your PixyScan one, which made a new, empty account. Disconnect, connect again, and choose the Google account with your PixyScan email. If it is the right account, add a site first.
This Google account is already connected to another PixyScan account	Wrong Google account	That Google account belongs to a different PixyScan account. Sign in with the Google account that has your PixyScan email.
Unauthorized, invalid_token, or a request to sign in	Sign-in ran out	Sign in again from your assistant. See Staying signed in.
This site has never been scanned.	No scan yet	Start a scan in the app, wait for it to finish, then ask again.
A scan of this site is running now.	Scan running	Wait for the scan to finish, then ask again.
This site has no readable scan. The most recent attempt failed	Scan failed	Open the site in the app to see why the scan failed, then start a new one.
"…" matches … sites equally well	Unclear site	Name the site by its full address, or say which workspace it is in.
You cancelled the Google sign-in.	Sign-in closed	The browser window was closed before you approved. Connect again and finish the Google step.
It answers without using PixyScan	Tools off	Check that PixyScan is switched on for this chat, or that the server shows as connected, and mention PixyScan in your question.

Does something here not match what you see in the app? Tell us