Connect SEOReport to OpenAI Codex CLI: MCP setup for SEO audits

What you need

You need an active SEOReport plan and an API key. Create the key at https://seoreport.dev/dashboard/api-keys. API keys require an active plan. [3][4][1]

SEOReport shows the key once. Store it in a secret store or an environment variable, not in a prompt, a project file or your shell history. [4]

The server speaks streamable HTTP at https://seoreport.dev/mcp. It expects the key on every request as an Authorization: Bearer <api-key> header, the same key you use for the REST API. [3][4][1]

Add the server

Set the key as an environment variable in your shell profile, then register the server. --bearer-token-env-var takes the name of the variable whose value Codex sends as a bearer token, not the key itself. [6]

export SEOREPORT_API_KEY="sr__live_your_api_key"

codex mcp add seoreport --url https://seoreport.dev/mcp --bearer-token-env-var SEOREPORT_API_KEY

[mcp_servers.seoreport]
url = "https://seoreport.dev/mcp"
bearer_token_env_var = "SEOREPORT_API_KEY"

Codex keeps MCP servers in ~/.codex/config.toml by default. You can also scope a server to one project with .codex/config.toml, in trusted projects only. [5]

Codex waits 60 seconds by default for a tool to run (tool_timeout_sec). A SEOReport report takes up to about 30 seconds, so the default leaves room. [5][4]

Confirm it works

Run codex mcp list to see configured servers, or codex mcp get seoreport to show this server's entry. In the codex TUI, type /mcp to see your active MCP servers. [5][6]

You should see 9 tools whose names start with seoreport_: seoreport_create_report, seoreport_get_report_status, seoreport_get_report, seoreport_list_reports, seoreport_get_report_download, seoreport_get_account, seoreport_list_plans, seoreport_start_checkout and seoreport_submit_feedback. [3]

Then try a first prompt: "Audit https://example.com and list the three highest-severity findings." The agent can start the audit with seoreport_create_report and read the findings with seoreport_get_report. A report takes up to about 30 seconds. [4][3]

A new site uses one credit from your plan. Running a site you already have a report for again does not use a credit. [1][2]

Keep the key out of version control

bearer_token_env_var stores only the variable's name, so config.toml holds no key. Avoid http_headers for the key: Codex documents it as a map of header names to static values. [5]

Set SEOREPORT_API_KEY in your shell profile or a secret manager, not in a file inside the repository. [4]

Troubleshooting

Authentication error or HTTP 401: SEOReport lists and calls tools only for a valid key. Check that the header value is Bearer, one space, then the key. If the key may be wrong or exposed, revoke it and create a new one in the dashboard. [3][4]

If you get a 401, check that SEOREPORT_API_KEY is set in the shell where you start Codex. That is our reading of bearer_token_env_var, which names the variable Codex reads the token from. [5]

Plan or credit error: if seoreport_create_report says an active plan is required or the month's credits are used, the key works but the account cannot start a report. Ask the agent to call seoreport_get_account to see the plan and the credits left. [4]

To subscribe from the agent, it can call seoreport_list_plans and then seoreport_start_checkout. Checkout returns a browser link: an agent can start it, and only a person can pay. Credits reset on the first day of each month (UTC). [4][1]

Tools not listed: check that the server's enabled option is not set to false and that no enabled_tools or disabled_tools list hides SEOReport's tools. A server has 10 seconds to start by default (startup_timeout_sec). [5]