Codex + Semurai
Set up Semurai as a Codex MCP server once, and the Codex CLI, IDE extension and app can research keywords, read Search Console and pull article drafts into your repository. Made for sites whose content lives in Markdown or MDX. One address, OAuth sign-in, no API keys.
Codex CLI · IDE extension · Codex app
Add Semurai from your terminal
codex mcp add semurai --url https://api.semur.ai/mcp
codex mcp login semuraiSetup
Two commands in your terminal. Codex saves the server in its configuration, which the IDE extension and the Codex app read too.
In your terminal, run the codex mcp add command from the Terminal snippet.
Run codex mcp login semurai. Codex opens a Semurai page in your browser.
Sign in to Semurai, pick a default workspace and click Allow.
Start Codex in your project and ask for something that needs search data. Codex calls the Semurai tools it needs.
codex mcp add semurai --url https://api.semur.ai/mcp
codex mcp login semurai[mcp_servers.semurai]
url = "https://api.semur.ai/mcp"Good to know
~/.codex/config.toml, then run codex mcp login semurai. A trusted project can keep it in .codex/config.toml instead.Use cases
Codex for SEO means search data next to your source files: Codex edits the content, Semurai tells it what people search for.
Your blog lives in Markdown or MDX files, and Codex already edits them. Semurai adds the search data, so a change to a post starts from volume and intent.
Codex finds pages with plenty of impressions and few clicks in Search Console, then rewrites their meta titles and descriptions in the source.
One codex exec command reads the week’s position changes from your Semurai rank tracker and writes them to a Markdown file in the repository, ready for Monday.
An article written and reviewed in Semurai’s SEO editor comes back through get_content as Markdown, ready to save as a new post.
Codex compares your domain with up to five competitors in Semurai and adds the missing topics as tasks on the Semurai board, where your editors pick them up.
Help centres and docs get searched too. Codex checks volume and related questions for a topic, then shapes the headings around what people ask.
Example
Codex reads the numbers from Semurai and edits the files behind them.
Some of our blog pages get impressions but few clicks. Check them in Semurai and fix the titles and descriptions of the weakest ones.
Three blog pages with many impressions and few clicks:
| Page | Impressions | CTR | Position |
|---|---|---|---|
| /blog/french-press-guide/ | 12,400 | 0.9% | 6.2 |
| /blog/decaf-explained/ | 8,150 | 1.1% | 7.8 |
| /blog/grinder-settings/ | 5,320 | 1.4% | 5.4 |
I found their files in content/blog and rewrote each title and description in the front matter around the phrase with the most searches from the keyword check. Shall I run the build?
Yes, run it.
Build passed. Three files changed in content/blog, ready for your review before you commit.
Prompts to try
CLI, IDE or app
All three read the same MCP configuration. Add Semurai in whichever one you open first.
| Codex CLI | IDE extension | Codex app | |
|---|---|---|---|
| Where you add it | codex mcp add or config.toml | Gear menu → MCP servers → Add server | Settings → MCP servers |
| How you sign in | codex mcp login semurai | Restart extension, then Authenticate | Restart, then sign in when Codex asks |
| Good for | Terminal sessions and scripted runs with codex exec | Fixing the content files you have open | Handing Codex a task away from the terminal and the editor |
semurai and the URL https://api.semur.ai/mcp, then save.semurai and the server address.Scripts and teams
Run Semurai reports from a script, give Codex a standing SEO instruction, or pick the coding agent that fits your team.
codex exec runs Codex without the interactive session, so a weekly ranking summary is one command. Codex reads your tracked keywords in Semurai and writes the summary into the repository as Markdown.
codex exec "Use Semurai to list our tracked keywords with their weekly change. Write the five biggest moves and a short comment to reports/rankings-weekly.md."Put the command in a script you run every Monday, and the reports build a history in Git next to your content.
Codex follows the project instructions in AGENTS.md. A short section like this one makes keyword research part of its routine:
## SEO
Before you write or edit a blog post, check its target keyword in Semurai:
search volume, difficulty and the questions people ask.
Use those questions as headings where they fit.| Codex | Claude Code | |
|---|---|---|
| Add Semurai | codex mcp add | claude mcp add |
| Sign in | codex mcp login semurai | /mcp in Claude Code, or claude mcp login semurai |
| Configuration | ~/.codex/config.toml, shared by the CLI, IDE extension and app | Local, project (.mcp.json) or user scope |
Both reach the same 62 Semurai tools with the same account. Using Claude Code? See the Claude Code page. For research and plans in a chat, ChatGPT connects too.
Other assistants
The same server address and the same Semurai account work in every assistant below.
FAQ
Run codex mcp add with a name and the server URL. For Semurai: codex mcp add semurai --url https://api.semur.ai/mcp, then codex mcp login semurai to sign in. You can also write the server into config.toml, or add it under MCP servers in the IDE extension or the Codex app.
In the config.toml file, as an [mcp_servers.semurai] table with the server url. The CLI, the IDE extension and the Codex app all read it.
Yes, when the server is in ~/.codex/config.toml: that file applies to all your projects. A trusted project can also have its own .codex/config.toml, for servers that belong to that repository only.
Yes. The Codex CLI, the IDE extension and the Codex app share one MCP configuration, so a server you add in one of them is available in the others.
With OAuth. codex mcp login semurai opens a Semurai page in your browser, where you sign in, pick a default workspace and click Allow. No API key goes into the config file, and the access token renews on its own.
Yes, in two ways. Codex can research the keyword in Semurai and write the post itself as a Markdown or MDX file. Or Semurai writes the full draft in its SEO editor, and Codex brings it into the repository with get_content, which returns the body as Markdown.
It can, through the full server. Add it next to your semurai entry with codex mcp add semurai-full --url https://api.semur.ai/mcp/full and sign in with codex mcp login semurai-full. Since the CLI, the IDE extension and the app share one configuration, all three get the graphics tools: AI images saved to your media library, Canvas and Creative Studio designs, and alt texts, titles and tags for library images. Codex can also answer the designer’s questions, revise a design or go back to an earlier version without leaving your editor or terminal. The full server needs its own approval in Semurai.
Yes. Actions Codex runs in Semurai count toward the workspace’s usage limits, exactly as if you ran them in the Semurai app. Codex reading and editing files in your repository does not involve Semurai.
The default workspace you picked when you clicked Allow. Ask Codex to list your workspaces and it can work in another one, with your role in that workspace.
Create your Semurai account, run codex mcp add and codex mcp login, and give Codex its first SEO task.
