Connect Codex to Searcherries

Connect Codex to the Searcherries remote MCP server so it can read your collected project data. You need Codex (the desktop app, the IDE extension or the CLI) and paid-plan access in Searcherries. The three share one local Codex configuration, so you only set the server up once.

The same connection details are displayed under Codex on the MCP page.

Connect in the desktop app

1. Open Settings → MCP servers and choose Add server.
2. Name it Searcherries, choose Streamable HTTP and paste https://app.searcherries.com/mcp/searcherries.
3. Save, restart the connection if prompted, then select Authenticate and sign in to Searcherries.
4. Open a new conversation and ask: "List my Searcherries projects."

For the Codex IDE extension, open its MCP settings and add this section to config.toml, next to any servers already configured:

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

Then complete authentication in the client or with the sign-in command below.

Connect from the CLI

Run this command in your terminal:

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

Then sign in:

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.

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, confirm your Searcherries subscription 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.