Connect Codex to Searcherries

Connect Codex to the Searcherries remote MCP server so it can read your collected project data. You need Codex (the CLI, the desktop app or the IDE extension) and a Searcherries account with a project; the free plan serves Search Console and GA4 data, AI visibility data needs Starter, Pro or Agency. The three share one local Codex configuration, so you only set the server up once.

The same commands are displayed under Codex on the MCP page. Codex has no install link for MCP servers, so the one-line command below is the shortest path; the plugin route further down adds eight ready-made GEO skills.

Connect from the CLI

Run this command in your terminal. It registers the server and starts the sign-in:

codex mcp add searcherries --url https://app.searcherries.com/mcp/searcherries && codex mcp login searcherries

Complete the Searcherries authorization flow in the browser. Check that you are signed in to the account whose projects you want Codex to read.

Browser authorization does not require you to generate a personal access token or manually copy the Claude OAuth Client ID.

Or install the plugin from the CLI

The Searcherries plugin for Codex adds the same MCP server plus eight GEO skills: $action-plan, $geo-audit, $content-gaps, $competitor-gap, $page-brief, $question-review, $weekly-report and improve-ai-visibility. Codex installs plugins only from a registered marketplace, so this command registers the Searcherries marketplace from GitHub, installs the plugin and starts the sign-in:

codex plugin marketplace add eduardmur/searcherries-codex-plugin && codex plugin add searcherries@searcherries && codex mcp login searcherries

Start a new Codex session afterwards: bundled skills and servers appear only in sessions started after the install. /plugins opens the plugin browser, $ followed by a skill name runs a workflow, and codex plugin marketplace upgrade searcherries fetches updates. The marketplace is the public repository eduardmur/searcherries-codex-plugin.

Codex CLI 0.163 also lists the ChatGPT plugin directory as a built-in marketplace named openai-curated-remote, so codex plugin add searcherries@openai-curated-remote installs the directory package (the server and the improve-ai-visibility skill) without registering anything. OpenAI does not document that marketplace name, so it may change.

Install the plugin in the Codex desktop app

Codex in the ChatGPT desktop app uses the same plugin directory as ChatGPT, where Searcherries is listed. Open Plugins, search for Searcherries and select Install plugin, then approve access to Searcherries in your browser and start a new Codex chat. The plugin contains the MCP server and the improve-ai-visibility skill, which turns the findings into page changes in your website's code.

The IDE extension does not support plugins; use the CLI commands above or the configuration below there.

Or add the server by hand

In the desktop app, open Settings → MCP servers and choose Add server; in the IDE extension, the gear menu has the same MCP servers entry. Name the server Searcherries, choose Streamable HTTP, paste https://app.searcherries.com/mcp/searcherries, save and restart if prompted, then select Authenticate and sign in to Searcherries.

You can also add this section to ~/.codex/config.toml, next to any servers already configured, and run the sign-in command above:

[mcp_servers.searcherries]
url = "https://app.searcherries.com/mcp/searcherries"

Verify the connection

Run:

codex mcp list

Inside a Codex conversation, /mcp shows the connection state. In Codex, ask:

Use Searcherries to list my projects. Ask me which project to analyze if there is more than one.

After selecting a project, you can ask for a report based on the available visibility, competitor, citation, and analytics data.

For current Codex configuration details, see the official MCP documentation.

Use a personal access token when needed

If your client cannot complete OAuth, create a token on the Searcherries MCP page. Add the following configuration to the Codex configuration file, normally ~/.codex/config.toml:

[mcp_servers.searcherries]
url = "https://app.searcherries.com/mcp/searcherries"
bearer_token_env_var = "SEARCHERRIES_MCP_TOKEN"

Provide the token through an environment variable named SEARCHERRIES_MCP_TOKEN in the environment that launches Codex. Keep the token out of shared configuration files, repositories, and screenshots.

The token guide explains creation, replacement, and revocation.

Troubleshooting

If the server cannot be found, check that the URL includes /mcp/searcherries. If authorization fails, make sure the account has a project (the consent screen asks you to set up your site first) and repeat the browser login.

For token authentication, the variable must be available to the actual Codex process, not only to a different terminal session. If a token was revoked or expired, replace it.

The connection can read saved data but cannot run a new scan or change your project. A successful connection therefore does not make an old report current by itself.

Prompts and tools

The server exposes nine read-only tools (get-action-plan, list-projects, get-project-summary, get-ai-answers, get-search-performance, get-competitors, get-citations, get-ai-traffic, get-project-data) and seven prompts (action-plan, geo-audit, content-gaps, competitor-gap, page-brief, question-review, weekly-report) that contain ready recipes for the common jobs. Where Codex shows server prompts, pick one and pass the project name or id; otherwise ask Codex what to work on next, which calls get-action-plan, or ask it to start with get-project-summary for your project and follow the tool reference.