Connect Codex to Serpel over MCP

How do you add the Serpel MCP server to Codex?

1. 1

   Add the server.

   --url registers a streamable HTTP server. Codex stores the entry in ~/.codex/config.toml.

   codex mcp add serpel --url https://serpel.app/mcp

2. 2

   Sign in.

   This starts the OAuth login. Sign in to Serpel in the browser, choose the workspace and allow access.

   codex mcp login serpel

3. 3

   Check the server.

   codex mcp list shows the configured servers and codex mcp get serpel shows one entry. Then ask Codex a question about your site.

   codex mcp list
   codex mcp get serpel

Edit config.toml directly

You can write the same entry by hand. A url key makes Codex treat the server as a streamable HTTP server. Run codex mcp login serpel afterwards.

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

Sign out or remove the server

codex mcp logout serpel
codex mcp remove serpel

How does the OAuth sign-in work?

Codex follows the MCP authorisation specification: OAuth 2.1 with PKCE (S256). The server answers an unauthenticated request with HTTP 401 and a WWW-Authenticate header that points to the discovery documents. The client registers itself, opens /oauth/authorize in your browser and exchanges the code at /oauth/token. You do not need to create a client ID or a secret.

On the consent page you sign in to Serpel if needed, choose the workspace and review the permissions. The access token gets these scopes: mcp:read, projects:read, rankings:read, audit:read, keywords:read, keywords:write, recommendations:read, codebase:read. It only works at the MCP server. The REST API rejects it. Access tokens last 1 hour. Refresh tokens last 30 days and rotate each time they are used, so you stay signed in without doing anything.

To disconnect an app, open Settings, API, Connected apps in the dashboard. Disconnecting revokes the access and refresh tokens at once.

codex mcp login chooses the client registration method itself (auto). Serpel supports both dynamic client registration and client ID metadata documents, so the default works. You can force one for a single login with --oauth-client-registration cimd or --oauth-client-registration dcr.

How do you connect with a bearer token instead?

Use an API token when Codex cannot open a browser, for example on a server or in CI. Create the token in the dashboard under Settings, API tokens. It needs the mcp:read scope, plus the scopes of the tools you want to use:

• mcp:read: required for every call. Without it, the server answers with HTTP 403.
• projects:read: list_projects, get_project_overview, get_search_performance, find_keyword_opportunities, get_conversion_performance.
• rankings:read: get_keyword_rankings, get_ai_visibility, analyze_competitors, and get_job_status for rank checks, AI checks and monitoring runs.
• audit:read: get_crawl_issues, and get_job_status for crawls.
• recommendations:read: get_seo_recommendations.
• codebase:read: get_codebase_overview.
• keywords:write: research_keywords.

You can restrict the token to single projects. The tools then see only those projects.

The OAuth login happens in a browser. On a machine without one, give Codex the name of an environment variable that holds the token. Codex sends its value as the bearer token and never writes it to config.toml.

export SERPEL_TOKEN=vsk_your_token
codex mcp add serpel --url https://serpel.app/mcp --bearer-token-env-var SERPEL_TOKEN

[mcp_servers.serpel]
url = "https://serpel.app/mcp"
bearer_token_env_var = "SERPEL_TOKEN"

Which tools does the Serpel MCP server provide?

The server offers 13 tools. All of them check the scope, your project role and your workspace before they return data, so an agent only sees what you could see yourself. Lists hold at most 25 rows, and every result is compact JSON with a short summary sentence.

All tools except research_keywords are read-only and free. They never change your data or your website. Crawls, rank checks, AI visibility checks and monitoring runs do not start inside a tool call. You start them in the dashboard, with the CLI or through the REST API, and then follow them with get_job_status. Tools that need a data source, such as Search Console, tell the agent what to connect in the dashboard when it is missing.

In apps that can show interactive cards, such as ChatGPT and Claude, get_keyword_rankings, get_crawl_issues, find_keyword_opportunities and get_ai_visibility also show their result as a card. Every other client gets the same data as text. ChatGPT does not offer research_keywords.

How do agent spending and budgets work?

research_keywords is the only tool that uses credits, and it runs only when every one of these conditions holds. Serpel checks them in this order:

1. The token has the keywords:write scope. OAuth sign-in grants it.
2. The workspace has an active Starter or Pro plan.
3. The workspace owner allowed agent spending: “Agents can spend credits” under Settings, Billing, Agents and AI apps, or serpel agents allow.
4. One call costs at most 50 credits, and today’s agent spending plus the call stays within the daily limit. The default limit is 500 credits per day. You can set it between 1 and 100,000 with serpel agents daily-limit <credits>. The day follows UTC and resets at 00:00 UTC.
5. The workspace has enough credits. Serpel uses the monthly plan allowance first and then credits you bought.

A research for 25 keyword ideas costs 12 credits, and a research of the keywords a domain ranks for costs 6 credits. Fewer results cost fewer credits. Every result states the credits charged (credits.charged), your balance, the remaining monthly allowance and the remaining agent budget for the day (dailyAgentBudget). If the agent repeats a call after a network error, it passes the same requestId, and the research is charged once.

Tool results only link to the dashboard and to the pricing page. They never link to a checkout or a top-up, so an agent cannot buy credits for you.

Which prompts work well in Codex?

Ask in plain language. Codex starts with list_projects to find the project ID.

• “Use Serpel to find keywords that rank on positions 4 to 20 and propose three content changes for this repository.”
• “Check the Serpel crawl issues for my project and fix the five most severe ones in the code.”
• “Compare my tracked keywords with my competitors and write a short plan for the keywords where they are ahead.”
• “Which routes in this repository have no title or description according to Serpel’s codebase overview?”
• “Look up keyword ideas for ‘light roast coffee’ in the US. Show me the credit cost first and wait for my approval.”

The codebase overview needs a snapshot of your routes. Upload one with serpel scan --project <id>. The CLI reference explains the scan.

How do you troubleshoot the connection?

More about codex mcp and config.toml is in the Codex MCP documentation.