Nuwtonic AI SEO Agent Logo
Nuwtonic

Documentation

Connect Codex, Cursor, or Claude Desktop with the token from MCP Settings, then use the Nuwtonic tools.

Use Nuwtonic from Codex, Cursor, Claude, or another MCP client

MCP lets an assistant call Nuwtonic for you: Search Console data, GEO audits, AIO and SEO advanced fixes, on-page SEO audits, articles, prompt tracking, and reports.

Open MCP Settings from the account menu. Copy the MCP URL there, and have an organization admin generate the bearer token. The token belongs to the organization. The same token works for every workspace in that organization.

Copy the domain and workspace id from MCP Settings and pass them when you ask for that site's data. The bearer token already identifies the organization.

If you only need the product screens, start with the User Guide. Search Console tools also need Google Search Console connected for that site.

1. Before you start

Check these before you connect a client. Each missing item blocks a later step.

  1. You are signed in to the organization you want the assistant to use.
  2. That organization has at least one workspace, and the workspace has a site URL. Name that site when you ask the assistant to do something.
  3. You can open that workspace in Nuwtonic. If you cannot, ask an organization admin to give you access.
  4. An organization admin is available to generate or revoke the token.
  5. For Search Console tools, the property is already connected in Nuwtonic.
  6. For publishing or applying fixes, the CMS or webhook integration for that workspace is already connected.

MCP does not create organizations or workspaces. Create them in Nuwtonic first.

2. What MCP Settings gives you

Each organization has one active bearer token. It is for the organization, not for one workspace. Use that same token for any site in the organization.

Field on the page What to do with it
MCP URL Copy this from MCP Settings and paste it into the client.
Bearer token The secret. Shown only once, immediately after you generate it. Use this when the client asks for the token alone.
Authorization value The same secret with Bearer in front. Use this when the client asks for an Authorization header.
Organization ID Shown for reference. The bearer token already identifies the organization.
Domain The site to fetch, such as example.com. Copy it and pass it with the MCP request for that site.
Workspace ID The id of that site's workspace. Copy it and pass it with the domain when you ask MCP for that site's data.

Copy the MCP URL from MCP Settings. Paste that address into the client. Do not type a different address.

3. Generate the token

  1. Open MCP Settings.
  2. Enter a short label you will recognize later, such as Codex or Claude. The label can be at most 80 characters.
  3. Choose the site whose data you want. Copy its domain and workspace id. Pass those when you ask MCP for that site. The token still covers the whole organization.
  4. Click Generate token.
  5. Copy the bearer token and the Authorization value before you leave the page.

The token cannot be shown again. Click I have copied the token only after it is saved in the client. If you did not copy it, revoke the token and generate a new one.

A second token is blocked while one is active. Revoke the active token first, then generate the next one. Revoking stops that client immediately. You do not need a new token to use another workspace in the same organization.

4. Connect Codex

Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share this configuration.

The token itself belongs in an environment variable. The config file stores only the variable name. Codex sends it as Authorization: Bearer <token>. Put the raw token in the variable, without the word Bearer.

Windows (current PowerShell window):

$env:NUWTONIC_MCP_TOKEN = "paste-the-bearer-token"

Start Codex from that same window. A new window does not keep this value. To keep it for new windows, set NUWTONIC_MCP_TOKEN in Windows environment variables, then open a new terminal.

macOS or Linux:

export NUWTONIC_MCP_TOKEN="paste-the-bearer-token"

Add the server in ~/.codex/config.toml (on Windows, %USERPROFILE%\.codex\config.toml):

[mcp_servers.nuwtonic]
url = "paste-the-mcp-url"
bearer_token_env_var = "NUWTONIC_MCP_TOKEN"

Or from a terminal where the variable is already set:

codex mcp add nuwtonic --url "paste-the-mcp-url" --bearer-token-env-var NUWTONIC_MCP_TOKEN

Restart Codex after you save the config. In the Codex terminal UI, /mcp lists the server. If Codex says the environment variable is not set, the variable is not visible to the Codex process. Set it again in the environment that launches Codex, then restart Codex.

5. Connect Cursor

Cursor reads ~/.cursor/mcp.json for every project, or .cursor/mcp.json inside one project. Do not commit the token. A project file should use an environment variable.

Global file (%USERPROFILE%\.cursor\mcp.json on Windows):

{
  "mcpServers": {
    "nuwtonic": {
      "url": "paste-the-mcp-url",
      "headers": {
        "Authorization": "Bearer paste-the-bearer-token"
      }
    }
  }
}

Project file that you might commit:

{
  "mcpServers": {
    "nuwtonic": {
      "url": "paste-the-mcp-url",
      "headers": {
        "Authorization": "Bearer ${env:NUWTONIC_MCP_TOKEN}"
      }
    }
  }
}

Save the file and restart Cursor. The header value must start with Bearer , then one space, then the token from MCP Settings. The Authorization value field on that page is already in that form.

6. Connect Claude Desktop

Claude Desktop, Claude on the web, and the Claude mobile apps use the same connector. Claude calls Nuwtonic from Anthropic's servers, so paste the public MCP URL from MCP Settings.

  1. Open Claude Desktop.
  2. Go to Customize → Connectors.
  3. Add a custom connector:
    • On Pro or Max, click + Add, then Add custom connector.
    • On Team or Enterprise, an owner adds it first from Organization settings → Connectors → Add → Custom → Web. A Free plan can add one custom connector.
  4. Name it Nuwtonic.
  5. Paste the MCP URL and continue.
  6. Under Authentication, choose No sign in.
  7. Under Request headers, add one header. Name it Authorization. For the value, paste the Authorization value from MCP Settings. It already starts with Bearer and a space.
  8. Click Add.

Open a chat, click +, open Connectors, and turn Nuwtonic on. If the toggle is off, Claude cannot use Nuwtonic in that chat.

If you are on Team or Enterprise and you are not an owner, wait until Nuwtonic appears under Customize → Connectors, then click Connect. On those plans the Authorization header is shared by everyone who uses the connector. Add it only for people who should use this Nuwtonic organization.

To replace the token, remove the connector and add it again. Claude does not edit a connector in place.

If Nuwtonic does not connect, check three things, then remove it and add it again:

  • The URL is the MCP URL you copied from MCP Settings.
  • Authentication is No sign in.
  • The header name is Authorization, and the value is the Authorization value, not the raw token alone.

7. Sign in instead of pasting a token

Some clients offer Sign in instead of a pasted token.

  • Codex: run codex mcp login nuwtonic after the server URL is configured.
  • Cursor: add the MCP URL without a bearer header, then use the server's sign-in.
  • Claude: when you add the connector, choose Sign in now instead of No sign in, and leave the Authorization header empty.

Use the email on your Nuwtonic account. Nuwtonic emails a 6-digit code. Enter that code. It expires in 10 minutes.

That sign-in can use the workspaces linked to that email. The MCP Settings token is separate: it belongs to the organization and works for every workspace in it. If sign-in does not finish, use the bearer token instead.

If the signed-in email cannot open the workspace, the tool says so. Sign in with the Nuwtonic account that can open that workspace, then try again.

8. What to ask for

Ask for the outcome in plain language. From MCP Settings, copy the domain and workspace id of the site you mean and pass both with the request. The domain is the host only, such as example.com, without https:// and without a path. The token covers every site in the organization, so these two values tell MCP which site to fetch.

You do not paste website ids or job ids. When a job is still running, the tool tells the assistant what to check next.

Give both a start date and an end date when you want a range. Dates are YYYY-MM-DD, for example 2026-10-01. Leave both empty when you want the tool's usual period.

9. Tools

Google Search Console

Connect Search Console first. If it is not connected, these tools cannot return performance data.

Ask for clicks, CTR, position, trends, a page snapshot, a breakdown, or the rows for a page, query, device, or country.

GEO audit

Ask for a GEO / AIO audit of one or more page URLs. When it finishes, ask for the results or for the PDF of one page that was already audited.

This checks the AIO / GEO audit permission. If it is off, the tool tells you the next step. Turn that permission on for the workspace, then run the audit again.

A lifetime plan can audit one URL per request. Ask for the next URL in a new request.

Advanced fix

Advanced fix writes recommended changes for pages you already have. There are two kinds. Say which one you want, and name the site and the page URLs.

AIO advanced fix is for AI answers. Ask for an AIO advanced fix for those pages. Nuwtonic reads each page and saves AIO fixes. This is separate from a GEO audit. A GEO audit checks the page. An AIO advanced fix prepares the changes.

SEO advanced fix is for Google search. Ask for an SEO advanced fix for those pages. If you have Search Console numbers for a page, include them: the query, impressions, clicks, and position. Nuwtonic uses the page, and those numbers when you provide them, and saves SEO fixes.

Both run in the background. Ask again for the saved fixes when the work finishes. Say AIO or SEO so you get the right set. You can also ask for the saved fixes for a site without running a new analysis.

You can ask to change one saved fix on a page before it is applied. Say whether that fix is AIO or SEO.

Ask to apply the fixes only after the CMS or webhook for that site is connected. Applying writes the fixes to the site. See the WordPress, Shopify, Webflow, Ghost, or webhook guide for that site.

If a permission blocks the work, the tool names the switch to turn on for that workspace. Turn it on, then ask again.

A lifetime plan can run one page URL per request for an AIO advanced fix, and one page URL per request for an SEO advanced fix.

Articles

Ask for a new article and name the site. A standard article needs the keyword or keywords to write about. A lifetime plan can use one keyword per request.

Ask to publish it, or to save it as a draft. The CMS or webhook must already be connected. Generate and publish both check the content generation permission.

On-page SEO audit

Ask for one page URL to audit now, or for several page URLs at once. A single-page audit finishes in the reply. A bulk audit runs in the background; ask again for the stored results when it finishes.

A one-page audit does not depend on the scheduled on-page automation switch.

Lifetime plans cannot run a bulk audit. Ask for one page URL, then ask again for the next page.

Prompt tracking

Ask to list, add, change, remove, or run prompts that are already part of prompt tracking for your domain. These tools do not create a workspace.

To add a prompt, give the wording. Each prompt is at most 2,000 characters. If you set a country, use a 2-letter code such as US or GB, not the country name.

You can set how often a prompt is checked: daily, every 3 days, weekly, every 15 days, monthly, or only when you ask.

A successful run uses one monthly prompt check. A prompt checked in the last 10 minutes is skipped. Asking how many checks a run will use does not use a check. If the monthly quota is used up, the tool says so. Change the prompts or wait for the quota to reset.

Reports

Ask for one of these:

  • The prompt tracking report
  • The GEO audit PDF for one page that was already audited
  • The on-page SEO audit PDF for the site, or for one page URL
  • The client review across search, SEO, GEO, and prompt tracking

A site SEO PDF uses the latest bulk or sitemap crawl. Run that audit first. The PDF does not apply any fixes.

If a part of the client review has no data, the result names that part and the reason. Fix the missing data, or ask for the report with the parts that are ready.

A saved download link expires in one hour. If it does not open, ask for the report again and use the new link.

A GEO or SEO PDF comes back in the reply when the file is 1.5 MB or smaller. A larger PDF is described, not attached. Ask for one page URL, or open the report in Nuwtonic.

10. Lifetime plans

A lifetime plan can run one item at a time from MCP for content generation, GEO audit, on-page SEO audit, and advanced fix.

What you asked for Limit
GEO / AIO audit One URL per request
AIO advanced fix One page URL per request
SEO advanced fix One page URL per request
A standard article One keyword per request
Bulk on-page SEO audit Not available. Ask for one page URL at a time

The tool names the limit and tells you to send one item, then ask again. Prompt tracking is not part of this limit.

11. When something fails

The tool result says what to fix. Use that sentence. These are the cases you will see:

What you see What to do
MCP URL is empty on MCP Settings Refresh the page, then copy the MCP URL shown there. If it is still empty, sign out and sign in again.
The token could not be loaded Refresh MCP Settings. If it continues, sign out and sign in again.
Organization is missing Refresh the page. If it continues, sign out and sign in again.
Enter a label Type a short name such as Codex or Claude, then generate again.
This organization already has an active bearer token Revoke the active token, then generate a new one. The new token still covers every workspace.
Only an organization admin can generate the bearer token Ask an admin to generate or revoke it.
You left the page before copying the token Revoke it and generate a new one. The old secret cannot be shown again.
Authentication failed The client is not sending Authorization: Bearer plus the current token. Paste the Authorization value again and restart the client. In Claude, remove the connector and add it again with that header.
This bearer token is not valid or has been revoked Generate a new token in MCP Settings and paste that one.
This bearer token belongs to a different organization Open MCP Settings in the organization that owns the site, and use that organization's token.
Unknown organization or workspace Name a site that already exists in this organization. MCP will not create a workspace.
The signed-in account cannot use this organization Sign in with the Nuwtonic email that can open that workspace.
Insufficient credits Add credits, then run the tool again.
Feature or automation permission blocked this action Read the message. Turn on the named permission for this workspace, then ask again.
Some required input is missing The message names what is missing, such as a page URL or a keyword. Add it and ask again.
The API timed out. Wait about 2 minutes, then retry Wait about 2 minutes. If it keeps happening, retry later rather than starting the same long job again immediately.
Lifetime plans can run one item at a time Ask again with one URL or one keyword.
Lifetime plans cannot run a bulk on-page SEO audit Ask for one page URL.
A report link does not open Ask for the report again and use the new link. The previous link expired.
The report PDF is too large to return Ask for one page URL, or open the report in Nuwtonic.
No tracked prompts matched Add a prompt, or ask to include paused prompts.
country must be a 2-letter code Send US or GB, not the country name.
The sign-in email could not be sent Use the bearer token from MCP Settings instead, or ask an admin to check the sign-in email setup.
Claude does not show Nuwtonic in the chat Click +, open Connectors, and turn Nuwtonic on. On a Free plan you can add only one custom connector. On Team or Enterprise, an owner has to add the connector before you can connect it.

12. What MCP does not do

These stay in Nuwtonic. Do not expect an MCP tool for them:

  • Creating an organization, a workspace, or a user
  • Showing the bearer token again after you hide it
  • Issuing a second active token for the same organization
  • Keyword research, rank tracking outside prompt tracking, brand visibility, and brand analysis
  • Performance Ask AI, GA4, Bing, analytics exports, lead-gap snapshots, and brand work plans
  • Credit balance
  • Quota top-ups and the prompt-tracking schedule

The same token works for every workspace in the organization. Name the site when you ask. To use a different organization, generate a token there. Revoking a token stops the client that was using it.