# OpenAI Codex



Codex connects like every other client: Streamable HTTP, one URL, an
`Authorization` header. There is no Surface-specific plugin to install.

```json
{
  "mcpServers": {
    "surface-forms": {
      "url": "https://app.withsurface.com/mcp",
      "headers": { "Authorization": "Bearer <your-api-key>" }
    }
  }
}
```

<Info>
  That is the [generic MCP config](/mcp-server/setup#other-editors), 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.
</Info>

## What It Is Good At [#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](/build/forms-sdk/overview).

**Webhook receivers.** Point it at
[the webhook payload shape](/build/webhooks/submit-form) and let it write the
handler, the types and the tests in your service.

**Event instrumentation.** [Form events](/build/events/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 [#recommended-setup]

```
https://app.withsurface.com/mcp?tools=forms,vault,cms
```

The 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.

<Warning>
  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.
</Warning>

## Discovering Schemas at Runtime [#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 [#codex-and-openai-as-an-answer-engine]

ChatGPT is one of the four models scored in
[AI Visibility](/platform/ai-visibility/reading-the-score), and a human who
clicks through from ChatGPT arrives as an AI referral in
[traffic analytics](/platform/traffic/analytics), tagged by engine.