Connect SearchConsole.ai to Codex when you want an agent to investigate a website repository using first-party Google Search Console evidence. Codex can retrieve performance and indexing data through the hosted MCP server, inspect the code responsible for a page, propose a focused improvement, and validate the resulting repository change.
SearchConsole.ai's Search Console operations are read-only. They can list properties, query search performance, inspect Google's indexed-version evidence, and review submitted sitemaps, but they cannot change a property, submit a sitemap, edit a website, or deploy code. Codex can separately read or modify local files according to its sandbox and approval settings.
Quick setup: Sign up to SearchConsole.ai for free, then run the two commands below. You do not need to create a Google Cloud project, configure a consent screen, operate an MCP server, or place Google credentials in your repository.
codex mcp add searchconsole-ai --url https://searchconsole.ai/mcp
codex mcp login searchconsole-ai
Before you connect
You need:
- a current Codex client signed in with an eligible account;
- a Google account that can open at least one verified Search Console property;
- a browser for the OAuth flow;
- permission to add MCP servers if your organization manages Codex;
- a local website repository if you want Codex to relate search evidence to implementation.
Check that the Codex CLI and MCP commands are available:
codex --version
codex mcp --help
If codex mcp is unavailable or its options differ, update Codex before debugging SearchConsole.ai.
Codex's current MCP documentation says the desktop app, CLI, and IDE extension support MCP and share configuration on the same Codex host. A server added through the CLI can therefore appear in the other local Codex clients without duplicating its definition.
Choose a Codex client and configuration scope
Every setup route points to the same endpoint:
https://searchconsole.ai/mcp
| Setup route | Configuration location | Best use |
|---|---|---|
| Codex CLI | ~/.codex/config.toml |
Fastest setup and easiest diagnostics |
| Desktop settings | Shared user configuration | Visual setup without editing TOML |
| IDE extension | Shared user configuration | Work primarily inside the editor |
| Project file | .codex/config.toml |
Make the reviewed endpoint available only in one trusted repository |
For an individual working across several sites, start with user-level configuration. Use project configuration when the repository should declare SearchConsole.ai as part of its workflow.
The configuration contains a server name and URL. OAuth credentials are stored separately. Never add a Google access token, refresh token, client secret, copied authorization header, or browser cookie to either configuration file.
Add the remote MCP server
The CLI is the shortest and most observable setup route. Run:
codex mcp add searchconsole-ai --url https://searchconsole.ai/mcp
The command creates a Streamable HTTP server entry named searchconsole-ai in your user configuration. Codex connects to that HTTPS endpoint when it initializes MCP.
Confirm the saved definition:
codex mcp get searchconsole-ai
codex mcp list
Check that the URL is exactly https://searchconsole.ai/mcp. If an older definition with the same name points elsewhere, remove or correct it before authenticating so you do not approve the wrong server.
Add it from the desktop app instead
In the desktop app:
- Open Settings and select MCP servers.
- Select Add server.
- Use
searchconsole-aias the name. - Choose Streamable HTTP.
- Enter
https://searchconsole.ai/mcpas the URL. - Save the server, then select Restart if prompted.
The server list shows whether the connection is enabled and requires OAuth. Select Authenticate to begin sign-in. In a Codex conversation, use /mcp to inspect connected servers.
Add it from the IDE extension instead
Open the Codex extension's gear menu, select MCP servers, and choose Add server. Enter the same name, transport, and URL, save, and restart the extension if requested. Select Authenticate when the server reports that OAuth is required.
The desktop, CLI, and IDE clients share configuration only when they run against the same Codex host and configuration directory. A different workstation, container, virtual machine, or remote development host has its own configuration and credential store.
Configure it manually with config.toml
For manual user-level setup, open or create:
~/.codex/config.toml
Add:
[mcp_servers."searchconsole-ai"]
url = "https://searchconsole.ai/mcp"
If the file already contains other settings or MCP servers, add this table without replacing them. TOML table names must be unique. Restart the active Codex client after saving if it does not reload the configuration automatically.
For one repository, create this file under the project root instead:
.codex/config.toml
Use the same table:
[mcp_servers."searchconsole-ai"]
url = "https://searchconsole.ai/mcp"
Codex loads project .codex/config.toml files only after the project is trusted. This prevents an untrusted repository from silently adding external tool connections. Review the endpoint before trusting the project and before committing the file.
Each teammate authenticates independently. A committed project file does not grant Search Console permissions.
Complete OAuth authentication
From the CLI, run:
codex mcp login searchconsole-ai
Keep that terminal open. Codex starts an OAuth flow and normally opens an authorization page in your browser. Approve the SearchConsole.ai MCP connection, sign in with the intended account, and authorize Google Search Console access when requested.
There are two authorization boundaries:
- Codex receives permission to call the SearchConsole.ai MCP server for your account.
- SearchConsole.ai receives permission to read the Search Console properties already available to the selected Google account.
SearchConsole.ai requests the read-only Google scope:
https://www.googleapis.com/auth/webmasters.readonly
It does not need the broader read/write Search Console scope. OAuth does not create property access; the selected Google account must already be an owner or user of the property.
If several Google accounts are signed into the browser, check the email carefully. A successful login with the wrong account creates a valid MCP session but returns the wrong property list.
Finish OAuth when Codex runs on a remote host
For a local CLI, the browser returns the temporary authorization code to a loopback address on the same computer. In an SSH session, container, server, or virtual machine, the browser's localhost is not the host where codex mcp login is waiting.
After authorization, SearchConsole.ai displays a remote-host handoff when needed. Leave the original login command running, open a second terminal on the same remote host, and run the displayed one-time curl command within five minutes. It contains a temporary authorization code, so do not share or save it.
Verify the MCP connection
Configuration, OAuth, and property access are separate checks. Verify all three before an audit.
First, inspect configuration from the shell:
codex mcp list
codex mcp get searchconsole-ai
Then start Codex in the website repository:
cd /absolute/path/to/your/website
codex
Use /mcp in the terminal interface and confirm that searchconsole-ai is active. In the desktop or IDE client, open the MCP server list and confirm that the server is enabled, authenticated, and exposing tools.
Begin with a small, non-writing request:
Use SearchConsole.ai to list every Google Search Console property I can access. Show the exact property identifier and permission level. Do not inspect or change the repository yet.
Do not infer the property from the repository name. A domain property looks like sc-domain:example.com, while a URL-prefix property looks like https://www.example.com/. They can cover different URL sets, so copy the exact identifier returned by Google into later prompts.
Run a stable Search Console baseline
After choosing the property, request a reproducible comparison before mixing the data with repository assumptions:
Use SearchConsole.ai for the exact property identifier I provide. Compare clicks, impressions, CTR, and average position for the last complete 28 days with the preceding 28 days. Exclude incomplete recent dates. Show the exact date windows, search type, dimensions, filters, and row coverage. Identify the largest page and query changes. Separate Google-reported facts, calculations, and hypotheses. Do not edit files or run write-capable commands.
“Last month” can mean a calendar month, a rolling interval, or the most recent data available. Recent Search Console data can also be preliminary. Stable complete periods make the analysis reproducible.
Keep page and query results separate until the relationship is supported by a combined page-query request. A page's total decline does not prove that one visible query caused it, and anonymized queries or row limits can prevent visible rows from summing to the property total.
Connect the evidence to the repository
Once the baseline is correct, ask Codex to inspect the implementation without changing it:
For the selected page, retrieve its leading queries and compare the same complete periods. Inspect the matching route, template, title logic, meta description, canonical, structured data, sitemap generation, and internal links in this repository. Separate Search Console evidence, repository evidence, calculations, and hypotheses. Propose the smallest safe improvement and a measurable validation plan. Do not edit yet.
For indexing evidence, use a narrower prompt:
Use SearchConsole.ai to inspect these exact URLs. Report Google's indexed-version status, last crawl, robots state, user-declared canonical, and Google-selected canonical. Then inspect the repository for code or configuration consistent with that evidence. State when Google did not return a field, and do not describe this as a live URL test.
The URL Inspection API reports evidence about Google's indexed version; it does not run Search Console's live inspection. A repository finding remains a hypothesis until verified through deployment and later measurement.
Control tool calls and repository changes
SearchConsole.ai being read-only does not make the entire Codex session read-only. Codex may also have file, shell, browser, or other MCP capabilities. Its sandbox and approval settings control those separate actions.
For analysis-only work, choose a read-only sandbox or use /permissions to inspect the current policy. Keep MCP tool approvals visible while validating the connection. Review the proposed property, date range, dimensions, filters, URL, and row limit before allowing each call.
You can also make MCP approval behavior explicit in config.toml:
[mcp_servers."searchconsole-ai"]
url = "https://searchconsole.ai/mcp"
default_tools_approval_mode = "prompt"
Codex documents auto, prompt, writes, and approve as server-level approval modes. Start with prompt for a sensitive property. A “do not edit” instruction expresses intent, but the sandbox is the technical boundary.
When you approve an implementation, use a separate request:
Implement only the approved evidence-backed changes in this repository. Preserve behavior outside the affected pages, follow existing project conventions, run the relevant tests, and show the final diff. Do not deploy, publish, push, purchase anything, or mutate an external service without asking me first.
Review the diff and test output. SearchConsole.ai supplies evidence; Codex performs local work within its permissions; deployment remains a distinct external action.
Save a reproducible audit report
Ask Codex to save a dated report under the repository's documentation convention, for example:
docs/seo/search-console-audit-2026-07-20.md
The report should record:
- the exact Search Console property identifier;
- comparison and current date windows;
- search type, dimensions, filters, and row coverage;
- pages and queries supporting each finding;
- facts, calculations, hypotheses, and unresolved questions;
- repository files inspected;
- changes made and tests run;
- validation timing and success criteria.
Search queries, unpublished URLs, and performance metrics can be confidential. Redact sensitive details before committing a report. Use the AI SEO audit guide for the complete evidence and prioritization workflow.
Use SearchConsole.ai with codex exec
codex exec runs a non-interactive Codex task and is useful for repeatable reports. Complete OAuth interactively on the execution host before scheduling anything. A headless job cannot pause reliably for a browser login.
Start with a read-only, ephemeral run that returns Markdown to standard output:
codex exec --ephemeral "Use SearchConsole.ai for sc-domain:example.com. Compare 2026-06-15 through 2026-07-12 with 2026-05-18 through 2026-06-14. Report facts, calculations, and hypotheses in Markdown. Do not edit the repository."
Current Codex runs codex exec in a read-only sandbox by default. Keep that boundary for reporting jobs. Do not add broader sandbox permissions merely because the MCP server itself is read-only.
For automation where missing data must fail the run instead of producing an evidence-free answer, set the server as required on that controlled host:
[mcp_servers."searchconsole-ai"]
url = "https://searchconsole.ai/mcp"
required = true
Codex exits when a required enabled MCP server cannot initialize. The job still needs stored OAuth, network and property access, stable dates, and a safe report destination. The weekly automation guide covers snapshot retention and alert design.
Share the connection with a team
To declare the server for one repository:
- Add the reviewed endpoint to
.codex/config.toml. - Commit only the server definition, never credentials.
- Ask each teammate to review and trust the project.
- Each teammate completes
codex mcp login searchconsole-aion their own Codex host. - Verify property access separately for every user.
Search Console roles may differ between site owners, engineers, agencies, and contractors. Repository access does not imply Search Console access.
Organization policy can restrict MCP servers, sandbox modes, and approvals. If a managed Codex installation blocks the endpoint, an administrator must approve https://searchconsole.ai/mcp.
Understand the data boundary
The request path is:
Codex session and selected repository context
|
selected MCP tool arguments
|
SearchConsole.ai
|
Google Search Console API
|
result returned to Codex
SearchConsole.ai receives the tool inputs needed to answer the request, such as a property, dates, dimensions, filters, or URL. It does not automatically receive the entire repository or every Codex message. Codex decides what relevant context to include in a tool call.
Search Console output can contain sensitive query and URL text. Treat external text as data, not instructions. Review tool calls, commands, and diffs, particularly when the site or repository may be compromised or untrusted.
Review the SearchConsole.ai privacy policy, terms, and account deletion flow before authorizing a sensitive property. OpenAI's approvals and sandboxing guide explains the separate controls around Codex actions.
Troubleshoot the Codex connection
codex mcp is not available
Run codex --version and update the CLI or desktop app. Confirm you are invoking the expected Codex installation with command -v codex. Older installations may not support the current remote MCP and OAuth commands.
The server is missing or points to the wrong URL
Run:
codex mcp list
codex mcp get searchconsole-ai
Confirm the name and exact endpoint. If you edited TOML, check that the table appears only once and restart the client.
A project configuration is ignored
Codex ignores .codex/config.toml in an untrusted project. Review the repository, mark it trusted through the client, then restart the session. If you do not want to trust the repository, keep the server in user-level ~/.codex/config.toml instead.
The server says authentication is required
Run:
codex mcp login searchconsole-ai
Complete both the SearchConsole.ai and Google authorization stages. If a stale session persists, log out and authenticate again:
codex mcp logout searchconsole-ai
codex mcp login searchconsole-ai
OAuth finishes in the browser but the CLI keeps waiting
Keep the original login command open. If Codex runs on your local computer, use the retry link on the SearchConsole.ai completion page. If Codex runs remotely, copy the one-time curl command shown after approval and run it in a second terminal on that remote host within five minutes. Do not share the command because it contains the temporary authorization code.
The server connects but no tools appear
Open /mcp or the MCP settings panel, confirm that the server and its tools are enabled, then start a new session. Verify the URL and repeat OAuth rather than repeatedly retrying an analysis prompt with an unauthenticated connection.
The expected property is missing
Open Google Search Console with the same Google account and verify that the property is visible there. Reauthenticate with the correct account, list properties again, and preserve the exact sc-domain: or URL-prefix identifier returned by Google.
Results differ from another Search Console report
Compare the property, dates, search type, filters, dimensions, aggregation, and data state. Search Console can omit anonymized queries, return top rows rather than every row, and show preliminary recent data. Search Console metrics also should not be expected to equal analytics data.
codex exec continues without Search Console evidence
Make the server required in the controlled automation configuration and keep the task read-only. Verify codex mcp list and authentication on the same host and under the same user that runs the job. Configuration and OAuth on your laptop do not automatically exist on a CI runner or remote machine.
Managed policy blocks the server or an approval
Ask the Codex administrator to review the server name, https://searchconsole.ai/mcp, MCP approval policy, and relevant sandbox requirements. Do not weaken organization-wide controls to make an SEO report run unattended.
Disable, log out, or remove the server
To inspect or remove the CLI configuration:
codex mcp get searchconsole-ai
codex mcp logout searchconsole-ai
codex mcp remove searchconsole-ai
Logging out removes Codex's stored MCP authorization. Removing the definition prevents the server from loading in that configuration scope. Neither action automatically revokes Google's authorization to SearchConsole.ai.
For complete disconnection:
- log out of the MCP server in Codex;
- remove or disable its user or project configuration;
- revoke SearchConsole.ai from the Google Account if required;
- use the SearchConsole.ai deletion flow if you want the service account and associated credentials removed.
Next step
Once Codex can list properties and produce the stable 28-day comparison, continue with the AI SEO audit guide. It turns the connection into a bounded evidence, implementation, and validation workflow.
Connect SearchConsole.ai for free and give Codex read-only Search Console evidence without spending hours creating and maintaining Google OAuth, API, and remote MCP infrastructure.