Use SEOmatic in Codex

Connect Codex#

1. 1Add the server. In your terminal, run: codex mcp add seomatic --url https://app.seomatic.ai/api/mcp
2. 2Sign in. Your browser opens: sign in or create a free SEOmatic account and pick your site. If no browser opened, run codex mcp login seomatic.
3. 3Give SEOmatic time to load. Codex waits 1 second for MCP servers when a session starts, then goes on without them. Add mcp_optional_startup_grace_ms = 10000 near the top of ~/.codex/config.toml, above the first [section], so SEOmatic's tools are there from your first message.
4. 4Connect Search Console. If your workspace has no Search Console yet, Codex gives you a one-click link the first time it needs your data.
5. 5Ask your first question. Start Codex in your repo and ask “Use SEOmatic to audit my site and find the code behind each issue.”

# Add SEOmatic (opens your browser to sign in)
codex mcp add seomatic --url https://app.seomatic.ai/api/mcp
# Only if no browser opened:
codex mcp login seomatic

# ~/.codex/config.toml
# This line goes at the top, above the first [section]:
mcp_optional_startup_grace_ms = 10000

[mcp_servers.seomatic]
url = "https://app.seomatic.ai/api/mcp"

# Headless or CI: use a workspace API key instead
export SEOMATIC_API_KEY=smk_live_...
codex mcp add seomatic --url https://app.seomatic.ai/api/mcp \
  --bearer-token-env-var SEOMATIC_API_KEY
# then add required = true under [mcp_servers.seomatic]

# Optional: SEOmatic's 21 SEO skills
npx -y skills add Minh42/seomatic-mcp --full-depth -a codex

MCP Server, API Key or Skills: How Should Codex Connect?

Pick the MCP server with OAuth. One command and a browser sign-in, no key to store, and it works the same in the terminal and the IDE. Add the skills on top when you want Codex to run audits the same way every time.

Try Asking#

• “Use SEOmatic to audit https://example.com, then find the file responsible for each issue.”
• “Which pages have Google not indexed? Check our robots and canonical code for the cause.”
• “Find pages with lots of impressions and few clicks over the last 28 days, and rewrite their title logic.”
• “Audit the preview deploy at https://preview.example.com before I merge, and compare it with production.”
• “We moved from /es/ to /en/. How many old /es/ URLs are still indexed, and which return 404?”
• “Fix every page that ships without a meta description, starting with the ones that get the most impressions.”

What It Costs#

Connecting is free. Reading your own data never uses credits: Search Console performance and insights, index status, rankings, site audits, AI citations, traffic and your tasks. Only live market lookups (keyword metrics, search results, backlinks), AI visibility scans and the fixes you approve use AI credits; every tool is labelled free or billed. On the Free plan, market lookups count against 5 free questions a month. The workspace Owner sees every credit spent, by feature, in Settings > Usage. Codex itself is billed by its maker, not by SEOmatic: nothing on our side counts tokens.

Nothing Changes on Your Site Without Your Approval#

Codex changes your code inside its sandbox, with the approval rules you set, and you review the diff before anything ships. On the SEOmatic side, anything that would change your live site through a connected CMS is staged, never pushed. A staged change is a proposal: it says what will change and why, and in Approval mode nothing touches your site until you approve it. The assistant records your decision, and it is told never to approve anything on its own judgment. Approved fixes start within seconds, the page's previous state is stored, and any applied change can be rolled back. Changes that could take a page out of Google, like a noindex, need an extra explicit confirmation.

Codex says SEOmatic is connected but answers without my data.

Start a new chat and check that SEOmatic is enabled for that conversation in the tools menu. This is the step most people miss.

The SEOmatic page says "This connection request expired".

Start the connection again from Codex, or paste the setup prompt again.

The Authorize page shows the wrong email or no workspace.

Click Switch account on that page and sign in with the SEOmatic account that owns the site.

Why does Codex say it cannot change my site?

Fixes need a live paid plan or trial. On the Free plan, or when billing is paused or failed, your assistant can read and answer only.

How do I disconnect?

Open Settings > AI Agents, scroll to API Keys and delete the row named OAuth: Codex. See disconnect an assistant.