Published on npm as @wileai/codex-connectors-mcp. Every Codex plugin you've connected, available to any harness.

Your Codex plugins,
in any harness

An MCP bridge for connected Codex apps, direct web search, and macOS Computer Use. Codex keeps the logins. Your harness picks the model. No model turn, no API key.

{
  "mcpServers": {
    "codex-connectors": {
      "command": "npx",
      "args": ["-y", "@wileai/codex-connectors-mcp@latest"]
    }
  }
}

Requires Node.js 22.19+ and a signed-in Codex CLI (codex login).

01 · Plugins

Every Codex plugin.
Every harness.

Connect an app once in Codex — Gmail, GitHub, Figma, Linear, Slack, Google Drive, Notion, anything in the catalog — and use it from any agent harness through this extension.

Codex · Customize · Plugins
The Codex Plugins screen. The sidebar lists installed plugins: Slack, Tesseract, DoorDash, Figma, Granola, LinkedIn, Finances, Luma, Instacart, Linear, Gmail, Google Calendar, Google Drive, GitHub and Messages. The main pane shows the public catalog with Popular, New & Noteworthy and Productivity sections.
Everything under “Installed” here becomes MCP tools in your harness.

Codex already did the hard part: OAuth flows, token refresh, and a growing catalog of first-party app integrations. codex-connectors-mcp lifts those connected apps out of Codex and serves their tools over the Model Context Protocol, so any client that speaks MCP stdio or Streamable HTTP can call them.

Your harness never sees a credential. It sees tool names, schemas and results — exactly as Codex's app-server reports them, without truncation.

Works with
Claude CodeCursorPi CodexVS CodeZed WindsurfGooseyour own agent

Any client with MCP stdio or Streamable HTTP support that runs as the user signed in to Codex.

02 · How it works

A bridge, not an agent

The bridge drives Codex's own app-server directly. It never starts a model turn, so there's no inference cost and no second model in the loop.

Harness
Your agent
Picks the model, calls tools
Bridge
codex-connectors-mcp
Validates, asks, forwards
Codex
app-server
stdio, no turn/start
Auth
Codex login
Holds every credential
Apps
GitHub, Gmail, Figma…
Your connected plugins

MCP stdio | Streamable HTTP → JSON-RPC over stdio → mcpServer/tool/call

  1. Spawn codex app-server --listen stdio:// and initialize its experimental API.
  2. Open an ephemeral thread with apps enabled, model-adjacent features and your own MCP servers disabled.
  3. Read app/installed and keep only apps Codex reports as enabled and callable, filtered by your allowlist.
  4. Page through mcpServerStatus/list and join codex_apps tools to their apps by connector id.
  5. Expose each tool over MCP and validate every call against its original JSON Schema (draft-07, 2019-09, 2020-12).
  6. Forward through mcpServer/tool/call, preserving content blocks, structured content, errors and metadata.
  7. On shutdown, close the child process and remove its temporary workspace.
03 · Tools

Two ways to see your apps

Direct mode · default

Every enabled connector tool appears in tools/list with its full input schema and provider annotations, under stable ASCII names of 64 characters or fewer.

github_get_profile_3b5eaf4306c5
<app>_<tool>_<hash>  for every other tool
… plus dispatcher, web, and computer tools
Compact mode · CODEX_CONNECTORS_MODE=compact

Three connector management tools, plus enabled web and computer tools. App tools stay callable through the dispatcher, which is handy when a harness caps tool counts or hundreds of schemas would crowd the context.

codex_connectors({"connector":"GitHub","query":"profile"})
codex_connector_schema({"tool":"github.get_profile"})
codex_connector_call({"tool":"github.get_profile",
                      "arguments":{}})
ToolPurpose
codex_connectorsList apps; filter tools by connector and/or query; paginate with offset/limit; reload with refresh: true.
codex_connector_schemaThe full original tool definition, plus its exposed name.
codex_connector_callCall by original or exposed name with an arguments object.
codex_web_searchSearch, open, find, and follow result links. Cached by default; maximum access is configured by the user.
codex_computer_js, codex_computer_js_resetPersistent desktop JavaScript and reset, automatically available with the macOS runtime. App approvals use MCP forms.
codex_computer_status, codex_computer_forgetRuntime availability and grant revocation. Forgetting grants follows the write policy.
04 · Writes

Reads flow. Writes ask first.

Connector calls not marked read-only and Computer Use JavaScript/reset calls go through the write policy. Computer Use JavaScript runs with your user privileges; native app approvals do not sandbox it. Native app access also requires separate approval; your harness must authorize UI actions. By default you approve each write through MCP form elicitation, which shows the exact tool and arguments.

ask · default

Approve each one

The bridge shows the tool and its arguments in an elicitation form. Clients that can't elicit can't write.

allow

Trust the harness

For harnesses that already confirm MCP calls. The bridge adds no extra prompt.

deny

Read-only bridge

Reject anything not marked read-only, and everything marked destructive.

Calls time out after 120 s. If a write's outcome is unknown (timeout, cancellation, app-server crash), the bridge never retries it and blocks further writes until you've checked the app. Approval payloads over 20,000 characters fail rather than being silently shortened.

05 · Settings

Five variables. That's the config.

VariableDefaultPurpose
CODEX_CONNECTORS_CODEXcodexPath to the Codex executable.
CODEX_CONNECTORS_MODEdirectdirect or compact.
CODEX_CONNECTORS_WRITESaskask, allow or deny.
CODEX_CONNECTORS_WEB_SEARCHcachedMaximum access: disabled, cached, indexed, live.
CODEX_CONNECTORS_WEB_SEARCH_MODELgpt-5.4Standalone retrieval routing field; no model turn.
CODEX_CONNECTORS_COMPUTERautoAutomatic macOS runtime discovery; disabled opts out.
CODEX_CONNECTORS_COMPUTER_APP/Applications/ChatGPT.appDesktop runtime installation path.
CODEX_CONNECTORS_ALLOWAll eligible appsComma-separated connector names or IDs, case-insensitive. An explicitly empty value exposes no connectors. Web and computer access are configured separately.
CODEX_CONNECTORS_HTTP_TOKENUnsetBearer token for HTTP transport, at least 32 characters.

CLI flags: --transport stdio|http, --mode direct|compact, --port 8787, --help. Diagnostics go to stderr; stdout carries only MCP messages.

Streamable HTTP

For clients that want a URL instead of a subprocess. The listener binds to loopback only, checks Host and Origin, and requires the bearer token on every request.

Up to 16 independent sessions, each with its own lazily started app-server. Idle sessions expire after 30 minutes.

Client config
{
  "url": "http://127.0.0.1:8787/mcp",
  "headers": {
    "Authorization": "Bearer <CODEX_CONNECTORS_HTTP_TOKEN>"
  }
}
06 · Scope

What we didn't build

No model

The bridge never calls turn/start. Your harness's model does the thinking; Codex just serves the apps.

No API keys

Authentication stays with your codex login. The bridge does not read credential files. Standalone web retrieval uses an access token from app-server in memory, sent only to OpenAI.

No disk cache

Connector/web responses are forwarded without a disk cache. The desktop runtime may save screenshots/session artifacts.

No auto-retry

A write with an unknown outcome is never retried, and it blocks further writes until you've checked.

No hosted multi-user

It's a local, single-account bridge. Cloud-only harnesses need their own secured route to it.

No skill install

It bridges a plugin's app tools. Skills bundled with a Codex plugin stay in Codex.

Installing the bridge means sharing app names, tool schemas and tool results with your harness and its model provider. Read-only tools can still return private data, so use CODEX_CONNECTORS_ALLOW to share only the apps you intend to. This allowlist does not restrict web search or Computer Use; configure those separately.