# Set up the Greadme MCP server

> Instructions for an AI agent helping a person connect Greadme's MCP server to their AI client. Follow them one step at a time. Last updated 2026-11-03. The same steps for people: https://www.greadme.com/mcp-server#setup

Greadme audits websites for SEO, performance and AI visibility. Its MCP server lets an AI client run Greadme's checks for a signed-in Greadme account.

- Server URL: `https://www.greadme.com/mcp` (exactly this, with **www**: the address without www redirects, and clients drop the sign-in on a redirect)
- Transport: Streamable HTTP (remote). Name the server `greadme`.
- Sign-in: OAuth with a Greadme account (free to create). The client opens a Greadme sign-in page in the browser and the user approves the connection. There is no API key, client ID or secret.

## Rules for you, the agent

- Work out which client you are running in and follow only its section below: Claude, ChatGPT, Claude Code, Codex, Visual Studio Code.
- One step at a time, in short plain sentences. Wait for the user to finish a step before the next one.
- Run commands yourself only where a section says **You run this yourself**, and only after the user allows it. Everything else, the user does: tell them exactly what to press.
- Never ask the user for a password, a token or a code, and never handle one. The sign-in happens on Greadme's own page in their browser.
- Use the server URL exactly as written above.
- **Never tell the user Greadme is connected until a `check_ai_access` call through the Greadme server returns its result.** See "Confirm the connection".
- Already set up? If the client already lists a server for `https://www.greadme.com/mcp`, skip the install. If Greadme's tools are available to you, go straight to "Confirm the connection": a result there means the user is already signed in. Only a sign-in or authorization error means they still need to sign in.

## Claude Code

For Claude Code in a terminal, in an IDE extension or in the desktop app. You can run the install yourself.

0. **You run this yourself.** Check whether Greadme is already configured: `claude mcp list`. If a server points at `https://www.greadme.com/mcp`, skip step 1.
1. **You run this yourself.** Add the server. `--scope user` makes it available in every project, not just the current one.

   ```
   claude mcp add --transport http --scope user greadme https://www.greadme.com/mcp
   ```
2. **The user does this.** Sign in: type `/mcp` in a Claude Code session and choose Greadme, or run `claude mcp login greadme` in a terminal. Your browser opens the Greadme sign-in; approve the connection there.
3. **The user does this.** Ask Claude Code to use Greadme, for example to validate the JSON-LD in a page you are editing.

In the VS Code extension, the user types `/mcp` in the Claude Code chat to open the MCP servers list, chooses Greadme and signs in. Then confirm the connection (below). If `/mcp` does not list Greadme yet, the user starts a new Claude Code session and runs `/mcp` there.

## Codex

For the Codex CLI, the Codex app and the Codex IDE extension. You can run the install yourself.

0. **You run this yourself.** Check whether Greadme is already configured: `codex mcp list`. If a server points at `https://www.greadme.com/mcp`, skip step 1.
1. **You run this yourself.** Add the server. Codex starts the sign-in straight away and opens the Greadme sign-in in your browser. If it first reports that the provider rejected some scopes, that is expected: it retries with the ones Greadme allows.

   ```
   codex mcp add greadme --url https://www.greadme.com/mcp
   ```
2. **The user does this.** To sign in again later, run `codex mcp login greadme`. The server is saved in `~/.codex/config.toml`.
3. **The user does this.** Ask Codex to use Greadme's tools in a prompt.

The install command writes `~/.codex/config.toml` outside the workspace, so ask the user to approve it when your sandbox requires approval. It then opens the Greadme sign-in in the browser and waits until the user approves it: tell the user to finish the sign-in, and give the command a few minutes rather than a short timeout. Then confirm the connection (below), in a new Codex session if Greadme's tools are not available in this one.

## Claude

For Claude on the web, the desktop app and mobile. You cannot add a connector yourself: walk the user through these steps.

1. In Claude, open **Customize → Connectors** and choose **Add custom connector**. On a Team or Enterprise plan, an owner adds it under **Organization settings → Connectors**, and members then press Connect.
2. Name it `Greadme` and paste the server URL. Leave the OAuth option on **Use Claude's published identity**; there is no client ID or secret to enter.

   ```
   https://www.greadme.com/mcp
   ```
3. Press **Connect**, sign in to Greadme (or create a free account) and press **Allow** on the consent screen.
4. In a chat, turn on the Greadme connector and ask for a check. Claude asks before each tool call unless you choose to always allow it.

Then confirm the connection (below). If Greadme's tools are not available in this chat, the user turns the Greadme connector on in the chat's tools menu, or starts a new chat.

## ChatGPT

For ChatGPT on the web. You cannot add the server yourself: walk the user through these steps. (OpenAI removed ChatGPT's Developer mode; custom MCP servers are added from the plugins page.)

1. On the web, go to [chatgpt.com/plugins](https://chatgpt.com/plugins), press **Add** and choose **Add custom MCP server**. There is no Developer mode to turn on: your account and workspace settings decide whether you can add one, and on a Business or Enterprise workspace an admin may control it.
2. Name it `Greadme` and paste the server URL under **Server URL**. Leave **Authentication** on **OAuth**; under **Advanced OAuth settings** the client setup method stays on its default, Client ID Metadata Document (CIMD). There is no client ID or secret to enter.

   ```
   https://www.greadme.com/mcp
   ```
3. Tick **I understand and want to continue** and press **Create as a plugin**. In the window that follows, press **Connect Greadme**, sign in to Greadme and approve the connection. Greadme then shows under **Installed** on the plugins page.
4. In a new chat, choose Greadme from the **+** menu and ask for a check. The two free checks are marked read-only, so ChatGPT runs them without asking each time.
5. Connected Greadme before? Open Greadme on [chatgpt.com/plugins](https://chatgpt.com/plugins), press **Manage**, then **Refresh tools**, so ChatGPT loads Greadme's newer tools, such as the Page Audit, the Site Audit, the Content Audit and the AI Visibility Checker.

Then confirm the connection (below), in a new chat with Greadme chosen from the **+** menu.

## Visual Studio Code

For GitHub Copilot in Visual Studio Code. The quickest way is the install link: the user opens it, VS Code shows the Greadme server, and the user presses **Install**, trusts the server and approves the sign-in.

```
vscode:mcp/install?%7B%22name%22%3A%22greadme%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fwww.greadme.com%2Fmcp%22%7D
```

If you can run terminal commands and the `code` command is installed, this does the same: `code --add-mcp '{"name":"greadme","type":"http","url":"https://www.greadme.com/mcp"}'`. Otherwise the user adds it by hand:

1. In Visual Studio Code, run **MCP: Open User Configuration** from the Command Palette, add this entry under `servers` and save.

   ```
   "greadme": { "type": "http", "url": "https://www.greadme.com/mcp" }
   ```
2. Press **Start** above the entry, trust the server if asked, and allow it to sign in. Approve the connection on the Greadme page that opens. The entry then shows **Running** with Greadme's tools listed.
3. Open Copilot Chat in **Agent** mode and ask for a check, or name a tool with `#check_ai_access` or `#validate_schema`. Allow each call when asked.
4. If a check is cancelled, or the agent reads files instead of calling Greadme, see the troubleshooting below.

Then confirm the connection (below), in Copilot Chat in **Agent** mode.

## Confirm the connection (every client)

Greadme is connected only when a `check_ai_access` call through the Greadme server returns its result.

1. Call `check_ai_access` with `url` set to `https://www.greadme.com`. It is free, only reads, and stores nothing.
2. If it returns its report (whatever the report says about the page), tell the user Greadme is connected, and name one thing it found.
3. Anything else is not a confirmation: the tool missing from your tools, a sign-in request, an authorization error, a timeout or a tool error. Say plainly that Greadme is **not** connected yet, say what happened, and use the troubleshooting below.
4. Never say Greadme is connected, set up or working because a command succeeded, a config file was written, a sign-in page opened or the user says they finished. Only the call's result confirms it.

If Greadme's tools are not available in your current session after setup, the client may load new servers only when a session starts: ask the user to start a new session and paste this prompt there:

```
Use the Greadme check_ai_access tool on https://www.greadme.com and tell me whether the Greadme connection works. If the tool is not available, read https://www.greadme.com/mcp-server/setup.md and tell me what to fix.
```

## What the user can ask once connected

- `check_ai_access` (Check AI crawler access): Can ChatGPT, Claude and Google's AI read this page? Checks robots.txt for 12 major AI crawlers, noindex, JavaScript-only content and llms.txt. Example: "Can ChatGPT and Claude read https://example.com? Use Greadme."
- `validate_schema` (Validate structured data (JSON-LD)): Is this structured data valid? Checks the JSON-LD on a live page, or markup you paste, against schema.org and Google's rich result rules. A check of a live page is saved to your dashboard, as on greadme.com; it costs nothing. Example: "Validate the structured data on https://example.com/product with Greadme and tell me what blocks rich results."
- `start_content_audit` (Start a Content Audit): How good is the writing on this page? Runs a full Content Audit, scored in 8 categories with suggestions, AI access among them, and saves the report to your dashboard. It uses one Content Audit from your plan, given back if the audit fails. Example: "Run a Greadme Content Audit on https://example.com/blog/my-post and tell me the three changes that would help most."
- `start_page_audit` (Start a Page Audit): How fast and technically sound is this page? Runs a full Page Audit on mobile or desktop (Google PageSpeed plus Greadme's own checks, with an AI summary) and saves the report to your dashboard. It uses one Page Audit from your plan, given back if the audit fails. Example: "Run a Greadme Page Audit of https://example.com on desktop and tell me what slows it down."
- `start_site_audit` (Start a Site Audit): What is wrong across the whole site? Crawls up to 1,000 pages for SEO issues, broken links and 404s, and AI crawler access, stopping at 50 issues as on greadme.com, and saves the report to your dashboard. It uses one Site Audit from your plan, given back if the audit fails. Example: "Run a Greadme Site Audit of https://example.com and list the pages with missing titles or broken links."
- `start_ai_visibility_check` (Start an AI Visibility check): Do AI assistants recommend your site? Asks GPT, Claude and Gemini, each with live web search, two questions your customers might ask, then shows whether your site is named, in what position, and which competitors are named instead. Use your own questions, or let your assistant suggest some. The report is saved to your dashboard, and the check uses one AI Visibility check from your plan, given back if it fails. Example: "Check with Greadme whether ChatGPT, Claude and Gemini recommend example.com. Suggest two questions first."
- `get_audit_result` (Get an audit result): Audits run in the background. Your assistant uses this to fetch the result when it is ready, with a summary and a link to the saved report. It costs nothing. Example: "Is my Greadme audit finished yet? Summarize the result."
- `start_product_audit` (Start a Product Audit): Is this product page ready to sell? Runs a full Product Audit of one product, course, app or service page, scored in 10 categories with the largest fixes first, and saves the report to your dashboard. It uses one Product Audit from your plan, given back if the audit fails or the page shows no product. Example: "Run a Greadme Product Audit of https://shop.example.com/products/blue-mug and tell me the top three fixes."
- `get_product_audit_result` (Get a Product Audit result): A Product Audit runs in the background. Your assistant uses this to fetch its result when it is ready, with a summary and a link to the saved report. It costs nothing. Example: "Is my Greadme Product Audit finished? What should I fix first?"
- `list_scheduled_audits` (List scheduled audits): Which audits run on a schedule? Lists your Scheduled Audits with their next and last run, and the report or the reason a run failed. Example: "Which Greadme audits are scheduled for my sites, and did last week's runs work?"
- `create_scheduled_audit` (Create a scheduled audit): Run an audit every day or on chosen days, at your local time, with the report by email or notification and saved to your dashboard. Part of the Basic, Pro and Agency plans; each run uses one audit from your plan. Example: "Schedule a Greadme Page Audit of https://example.com every Monday at 8:00 London time and email me the report."
- `update_scheduled_audit` (Edit a scheduled audit): Change a scheduled audit's page, days, time, time zone, delivery or options. Example: "Move my weekly Greadme Site Audit to Thursdays at 7:30."
- `pause_scheduled_audit` (Pause a scheduled audit): Stop a scheduled audit for now, keeping its settings and reports. Example: "Pause the Greadme audit scheduled for example.com."
- `resume_scheduled_audit` (Resume a scheduled audit): Start a paused scheduled audit again from its next scheduled time. Example: "Resume my paused Greadme Content Audit schedule."

## Troubleshooting

### The connection fails or keeps asking me to sign in

Check the URL is exactly `https://www.greadme.com/mcp`. The address without **www** redirects, and assistants drop the sign-in on a redirect. If it still fails, remove the connector, add it again and sign in afresh.

### A check says the site could not be reached or was blocked

Greadme fetches the page like a visitor would. A site that is down, blocks automated requests or sits behind a login cannot be checked. Try the page in a browser first, or run the same check on greadme.com's AI Access Checker.

### In Visual Studio Code a check is cancelled, or the agent reads files instead

If another MCP server offers tools with the same names (an old or stopped entry), the agent may pick it and the call is cancelled: remove that entry.

If the project you have open contains similar code, the agent may read it instead of calling Greadme: open another folder, or enable only the Greadme tools under **Configure Tools** and name them with `#check_ai_access`.

### It says I have reached a limit

The limits reset on their own: the per-minute ones within a minute, the daily one at midnight UTC.

### My assistant is not in the list

Only the assistants above can sign in today. **Cursor** needs dynamic client registration, which Greadme does not offer; others may be added on request. Email support@greadme.com.

## Not supported yet

- Cursor: Cursor signs in only through dynamic client registration, which Greadme does not offer. It will work once Cursor supports Client ID Metadata Documents.