Codex + Wayfern

Codex reads the docs page as it is today.

~/.codex/config.toml
OAuth, or a token from a variable
Works with codex exec

Codex works in your repo and runs your tests. Its sandbox can block network calls, and what it knows about a library can be older than the version you use.

Add Wayfern to config.toml, and Codex calls scrape_page, search_web and crawl_site as MCP tools, with the sandbox left closed. The Codex CLI, the IDE extension and the ChatGPT desktop app read the same file.

~/app · zsh codex

~/.codex/config.toml saved

1[mcp_servers.wayfern]

2url = "https://api.wayfern.com/mcp"

$ codex mcp login wayfern

Opening wayfern.com in your browser… ✓ Logged in to MCP server 'wayfern'

$ codex exec "Read the Driftwood ORM v7

migration guide. Fix what breaks in src/db"

• Called wayfern.scrape_page(driftwood.dev/docs/v7/migrate)

└ 1 page as markdown · credits_charged: 1

• Edited 3 files +11 -7

└ src/db/client.ts +4 -3 ++++---

src/db/schema.ts +5 -2 +++++--

src/db/query.ts +2 -2 ++--

src/db/client.ts

- const db = driftwood.connect(url)

+ const db = createClient({ url })

wayfern.com/oauth/authorize

Allow Codex to use Wayfern?

Calls spend your credits.

Allow Cancel

Setup

Two lines of TOML and one sign-in.

Or run codex mcp add wayfern --url https://api.wayfern.com/mcp, which writes the same lines.

Add the server

~/.codex/config.toml

[mcp_servers.wayfern]
url = "https://api.wayfern.com/mcp"

2
Sign in

A browser opens on wayfern.com. Sign in and click Allow.
bash

codex mcp login wayfern
3
Check it

Start codex and type /mcp. It lists wayfern and its tools.

Run it

bash

codex exec "With the Wayfern tools, read the migration guide of our ORM, version 7, and list each change that breaks src/db"

Other ways to connect

A token for cron and CI

Cron cannot open a browser for OAuth. Put a wf_ token with the mcp scope in a variable, and Codex sends it as a Bearer token.
~/.codex/config.toml

[mcp_servers.wayfern] url = "https://api.wayfern.com/mcp" bearer_token_env_var = "WAYFERN_API_TOKEN"
As an agent skill

Codex loads skills from ~/.agents/skills, or .agents/skills in the repo. The skill runs curl, so the sandbox must allow network access, and it needs WAYFERN_API_TOKEN.
bash

mkdir -p ~/.agents/skills/wayfern curl -fsSL https://wayfern.com/skills/wayfern/SKILL.md -o ~/.agents/skills/wayfern/SKILL.md

Route

MCP needs no hole in the sandbox.

Codex makes MCP calls itself, so the shell sandbox can stay closed. The same config.toml serves the CLI, the IDE extension and the ChatGPT desktop app.

Remote MCP OAuth sign-in: Best fit; codex mcp login wayfern signs you in on wayfern.com.
MCP + token Authorization header: Works; bearer_token_env_var reads a wf_ token from a variable. Good for cron and CI.
Agent skill SKILL.md: Works; Put SKILL.md in ~/.agents/skills/wayfern. curl needs network access in the sandbox.
REST API api.wayfern.com/api/v1: Works; Codex can write code that calls api.wayfern.com/api/v1 directly.
Browser API Playwright over CDP: Works; Codex can write Playwright code that connects to a Wayfern browser over CDP.

Example tasks

Jobs for codex exec

01

Follow a migration guide

“Read the migration guide of the ORM we use, version 7, and change our models in src/db to match.”

scrape_page returns markdown for 1 credit.
02

Fix a CI error

“Search Bing and Google for this error from the CI log, read the two best answers and apply the fix.”

search_web bills 2 credits for each provider page. scrape_page is 1 credit a page.
03

Write a client from docs

“Crawl the REST reference of our SMS provider, 30 pages at most, and write a typed client in src/sms from it.”

crawl_site bills 1 credit for each page. crawl_status is free.
04

Check staging

“Capture the home, pricing and sign-up pages of staging at 1440 pixels wide and list anything that looks broken.”

capture_screenshot costs 5 credits a capture.

Tools

What Codex can call

The same tools on every route, at the REST API rates. Every result reports credits_charged.

All tool inputs

scrape_page Fetch one page through an anti-detect browser and return clean markdown, HTML, links and metadata. The screenshot, pdf and json formats add +4 credits (once); summary adds +2. 1 credit / page
extract_data Extract structured data from one or more pages with a prompt and an optional JSON Schema. Re-running over pages already fetched is free. 1 credit / uncached source page
map_site List a site's URLs from its sitemaps and page links. 2 credits / 10 URLs
capture_screenshot Capture a clean image of a page: cookie banners and ads removed, lazy images loaded, tall pages captured end to end. Returns a short-lived download URL and an artifact key, not image bytes. Slices of a full page cost nothing extra; a fail_if_contains match is not charged. 5 credits / capture
brand_profile Identity, colours, logos, social links and company metadata for a domain. 10 credits / profile
site_styleguide Colours, typography, spacing, radii, shadows and the design tokens a site declares. 10 credits / site
site_fonts Font families, where each is served from, available weights, file formats and where they are used. 5 credits / site
crawl_site Start a bounded multi-page crawl. Returns a job id immediately and charges nothing up front; pages are billed as the crawl runs. 1 credit / successful page
crawl_status Poll a crawl started with crawl_site and read a page of its results. The pages were billed as they were crawled. Free
search_web Search Google, Bing, and DuckDuckGo. Returns ranked results, ads, provider failures, pagination, and related queries. 2 credits / provider page
list_search_engines List live provider ids and labels. Free

Good to know

Tool timeout: Codex stops a tool call after 60 seconds by default. For a large extract_data run, raise tool_timeout_sec under [mcp_servers.wayfern].
Sandbox: codex exec runs read-only by default. Add --sandbox workspace-write when the job writes files.
ChatGPT on the web: It does not read config.toml. The ChatGPT page has the plugin steps.