Connect Codex to TweakThis

What you need

• A TweakThis account with a project for the site, and a URL rule for each address it runs on (local, preview, production).
• The TweakThis extension in Chrome or Firefox on desktop, signed in.
• The Codex CLI, run in the site’s repository.

1. Add the TweakThis MCP server

Add this block to your Codex configuration:

[mcp_servers.tweakthis]
url = "https://tweakthis.io/mcp"

[mcp_servers.tweakthis.oauth]
client_id = "d534c7ad-dc94-4315-898f-378e7096e3e6"
callback_port = 38502
callback_url = "http://127.0.0.1:38502/callback/kQ00A-t6xH7Y"

2. Sign in

codex mcp login tweakthis

Your browser opens TweakThis: choose the workspaces and projects Codex may use, and allow. There is no token to copy or store. Running Codex on another machine over SSH? Forward the callback port first (ssh -L 38502:localhost:38502 you@host) and open the printed link on your own computer.

Prefer a personal access token? Create one under Integrations → Access tokens in the dashboard, put it in the TWEAKTHIS_TOKEN environment variable and use this block instead:

[mcp_servers.tweakthis]
url = "https://tweakthis.io/mcp"
bearer_token_env_var = "TWEAKTHIS_TOKEN"

Ask Codex to work through the feedback

Each project page in the dashboard has a prompt to copy, with the project’s ID filled in, so the agent never has to guess the project from its name. It reads like this:

Use the TweakThis MCP server to work through feedback on the project "<project name>" (project ID <project-id>).
Only use this project ID; never choose a project by its name. Before editing, check that you are working in the repository <owner/repo>; if you are not, stop and ask me.

1. Call list_feedback with project_id "<project-id>" and status "open".
2. For each item, call get_feedback and use the note, expected and actual result, screenshot, selectors and page context to find the element in the code.
3. Make the change. If something is unclear, ask with add_comment instead of guessing.
4. Call submit_resolution with a short summary of what you changed and how you checked it. I review and accept it in the dashboard.

To work on one batch only, publish it as a review session and copy the prompt from the session page instead; it carries the session’s ID as well.

What Codex receives with each item

• The note in the reporter’s words, and the expected and actual result when given.
• The page URL and title, the viewport size and the device pixel ratio.
• The element or region: several selector candidates, a short excerpt of its HTML, its attributes and a few computed styles.
• A screenshot of the page and a crop of the element, with anything the reporter redacted blacked out.

Form input values are never read. Captured page data reaches the agent as evidence from the page, not as instructions to follow.

What happens next

1. The agent claims the item, so a second agent or a teammate does not work on it at the same time.
2. If the request is unclear, it asks one question. The item waits in needs input until you or the client answer in the dashboard.
3. It fixes the code and submits a resolution: what it changed and how it checked it. The item moves to ready for review.
4. The client, or you, accepts the fix or reopens the item with a note. Only a person can accept or dismiss an item; the agent cannot.

The tools

Any other agent that speaks MCP over Streamable HTTP can use the same tools with a personal access token; the MCP server page has the details. Questions? See the FAQ or pricing.

Using Claude Code as well? See Connect Claude Code to TweakThis.