OpenAI Codex
Connecting Codex to a Surface workspace, and the jobs it is best at: SDK forms, webhooks, and anything that touches your own repo.
Codex connects like every other client: Streamable HTTP, one URL, an
Authorization header. There is no Surface-specific plugin to install.
{
"mcpServers": {
"surface-forms": {
"url": "https://app.withsurface.com/mcp",
"headers": { "Authorization": "Bearer <your-api-key>" }
}
}
}That is the generic MCP config, not a
Codex-specific one, and Codex's own config format has changed more than once.
Translate the same three values into whatever shape your codex release
expects: the URL, Authorization: Bearer <key>, and HTTP transport.
What It Is Good At
Codex is best on jobs that span your repo and your Surface workspace at once.
Forms SDK work. The form definition lives in Surface, the markup lives in
your repo, and the binding between them has to agree. The loop is create_form
with sdk: true → get_sdk_binding_map → write the markup →
validate_form_html → publish_form. See
Forms SDK.
Webhook receivers. Point it at the webhook payload shape and let it write the handler, the types and the tests in your service.
Event instrumentation. Form events into your analytics layer, matching how your app already emits events.
Migrations. Moving off another form tool means reading an export, mapping fields, and creating forms in bulk: a script plus MCP calls.
Recommended Setup
https://app.withsurface.com/mcp?tools=forms,vault,cmsThe two default bundles plus the CMS family cover most build work. ?tools=
loads a different set rather than adding to the default, so vault has to be
named. Add ?readonly=1 on a second entry for exploring.
If your Codex setup has broad filesystem and shell access, that is fine for your
repo and less fine for a live workspace. Start it read-only and switch to a
writable connection only for the step that needs it. Form writes save a
draft until publish_form runs.
Discovering Schemas at Runtime
| Tool | Returns |
|---|---|
list_component_types | Every component a form can contain |
describe_component_type | The full shape of one component |
get_tool_schema | The JSON Schema for the heavy authoring tools |
Tell it those exist, so it reads the real shape instead of guessing a payload.
Codex and OpenAI as an Answer Engine
ChatGPT is one of the four models scored in AI Visibility, and a human who clicks through from ChatGPT arrives as an AI referral in traffic analytics, tagged by engine.