Before you start
- A DevTune project on a plan that includes API access. No account yet? Let your agent set one up.
- For the API key route: a project API key from API Keys in the account sidebar. DevTune shows the key once, so copy it when you create it.
Connect by signing in
Add the DevTune plugin marketplace:- Restart Codex.
- Open the plugin list and install DevTune.
- Sign in to DevTune when Codex opens the browser, select the project, choose the scopes the connection may use, and approve.
Connect with an API key
Use a key for scripts, scheduled runs and machines without a browser. Put the key in an environment variable and add the server. Codex saves the variable name, not the key:~/.codex/config.toml:
Check the connection
Runcodex mcp list. devtune shows as enabled, with OAuth or Bearer token under Auth. In a Codex session, /mcp lists the active servers.
Then ask Codex:
devtune_get_connection_context. If it names the wrong project, connect again and select the right one.
Measure
Ask Codex what AI platforms say and what AI systems fetch from your site:devtune_get_visibility_summary, devtune_get_visibility_diff, devtune_get_competitive_position, devtune_get_top_citation_pages, devtune_get_content_gaps, devtune_get_traffic_summary and devtune_get_404_demand. Measurement windows are 30 or 90 days.
Fix
Ask for the ranked fixes, then work one through:devtune_get_actionslists the queue with its evidence.devtune_change_action_statusaccepts an action, anddevtune_generate_action_briefwrites its brief. Generating a brief spends credits.- Codex reads the brief with
devtune_get_action_brief. Writing and publishing the page is your work and the agent’s, in your own repository or content system. DevTune drafts and never publishes. devtune_change_action_statuswithmark_liveand the published URL starts the before/after measurement.
Prove
devtune_get_outcomes_ledger returns each measured action as improved, mixed, no clear change, declined, still measuring or unmeasured. Results show what moved after a fix shipped, not what caused it. Results windows are 7, 30, 90 or 365 days.
What needs your approval
- Reading never changes your project or spends credits.
- Accepting an action, changing prompts or competitors, and every other change acts as you. Have the agent say what it will change before it does.
- Briefs, drafts, managed-agent runs, Agent Picks tests and prompt-set analysis spend credits. Approve the spend before the agent starts one.
- DevTune steers suggestions around locked pages and says when it did.
How Codex runs DevTune tools
The Codex CLI, the IDE extension and the ChatGPT desktop app share~/.codex/config.toml, so one setup covers all three.
Set how Codex asks before running DevTune tools with default_tools_approval_mode under [mcp_servers.devtune]: auto, prompt, writes or approve. writes asks only for tools that are not marked read-only.
Skills
The DevTune skills tell the agent which DevTune tool answers which question and how to report the numbers the way DevTune measures them. The plugin includes the DevTune skills. Without the plugin, add them yourself:Limits
- The plugin connection leaves out the managed-agent and Dex tools. Add the server with
codex mcp addto use them. - Codex stops waiting for a tool after 60 seconds by default. Raise
tool_timeout_secunder[mcp_servers.devtune]if a call times out. - ChatGPT on the web does not read your Codex configuration. See Use DevTune with ChatGPT.
- A connection reaches one project. Connect again, or use another key, for a second project.
- Tools your connection has no scope for do not appear in the agent. A connection never gains scopes added later. Edit the key, or disconnect and sign in again.
If something goes wrong
Next steps
- Codex documentation: how OpenAI documents connecting outside tools
- MCP server: every tool, its inputs and its scope
- Code mode: two tools in place of the full list, for agents short on context
- API authentication: keys and scopes
- Use DevTune with your agent: setup guides for other agents