Skip to content

Codex MCP server

A Codex MCP server lets Codex publish, schedule, reply, and read analytics across connected social accounts without leaving the coding environment.

Codex MCP server setup sequence
# Step 1: Register the hosted MCP server in Codex
codex mcp add <server-name> --url {{MCP_BASE_URL}}/mcp

# Step 2: Start Secure OAuth login and pause for user approval in the browser
codex mcp login <server-name>

# Step 3: Verify the connection before continuing
codex mcp list

# Step 4: After connection, call the tool to report available social accounts
# Tool: list_integrations
# Expected use: report which social accounts are available; do not publish immediately unless explicitly requested
Illustrative request
Example line 1

# Step 1: Register the hosted MCP server in Codex

Illustrative request
Example line 2

codex mcp add <server-name> --url {{MCP_BASE_URL}}/mcp

Illustrative request
Example line 3

# Step 2: Start Secure OAuth login and pause for user approval in the browser

The hosted setup described here exposes 36 MCP tools across 9 platforms through Secure OAuth. This guide shows the exact registration, login, verification, and account-listing steps an agent should follow, with a clear pause for user approval and a scheduling-first default.

What this setup does in Codex

A Codex MCP server connects Codex to a hosted MCP server for social media work. Once connected, Codex can publish, schedule, reply, and read analytics across your social accounts without leaving Codex. The setup described here exposes 36 MCP tools across 9 platforms. The setup is agent-led: Codex reads the instructions, registers the server, and pauses when you need to approve the secure sign-in. The connection uses Secure OAuth, so the user approves access in the browser and the agent never enters credentials for them.

Exact connection steps with commands and MCP URL

Follow the steps in order. First register the hosted MCP server with codex mcp add, using the server name and the hosted MCP endpoint ending in /mcp shown in the setup sequence example. Second, run codex mcp login and stop to ask the user to approve the connection in the browser. Third, run codex mcp list and confirm that the server is connected before continuing. Do not skip the verification step, and do not treat registration alone as a completed connection. The login step is a hard pause: if the user has not approved Secure OAuth in the browser, the setup is not complete.

Verification and listing available social accounts

After codex mcp list confirms the connection, call list_integrations and report which social accounts are available. Use that result as the source of truth for what can be published to, scheduled, replied to, or read for analytics. If the list is empty, stop and tell the user that no social accounts are available yet, and ask them to connect an account before any publishing or scheduling work begins. Do not assume an account exists because the MCP server itself is connected.

Scheduling preference and safety pauses

Prefer scheduling over immediate publishing unless the user explicitly asks to publish now. Scheduling gives the user a review point before content goes live and matches the default stated in the setup instructions. When the user does ask to publish now, confirm the target social accounts from the list_integrations result first, then proceed only with the accounts the user named. Keep replies and analytics reads separate from publishing so a read-only request does not accidentally create a post.

Failure matrix and troubleshooting

Use the failure matrix below to decide whether to continue, retry, or stop. A server that is registered but not logged in is not connected. A login that the user has not approved in the browser must not be worked around by entering credentials. A connected server with no available social accounts can support setup verification but cannot support publishing, scheduling, replies, or analytics for a specific account. In each failure case, report the exact step that failed and the next action the user needs to take.

Contract parity note and implementation dependency

This page is a staging specification for the setup workflow described above. The commands, order of steps, user-approval pause, list_integrations call, and scheduling preference are the contract to match. Any future implementation should preserve those behaviors exactly, including the pause for Secure OAuth approval and the rule that the agent never enters credentials for the user.

Setup steps and success checks
StepCommand or toolRequired actionSuccess check
1codex mcp add <server-name> --url {{MCP_BASE_URL}}/mcpRegister the hosted MCP server with the MCP URL ending in /mcpServer appears in Codex MCP configuration
2codex mcp login <server-name>Pause and ask the user to approve Secure OAuth in the browser; never enter credentials for themUser approval completed in browser
3codex mcp listVerify the server is connected before continuingServer shown as connected
4list_integrationsReport which social accounts are availableAvailable social accounts listed for the user

Exact command syntax and order preserved; server name shown as <server-name> and MCP origin as {{API_BASE_URL}} in public copy per branding policy, with exact literals retained privately for implementation matching. MCP URL path is /mcp.

Failure matrix
FailureWhat it meansWhat to do nextDo not do
Server not shown as connected in codex mcp listRegistration or login is incompleteRe-run registration if needed, complete codex mcp login, then verify again with codex mcp listDo not call list_integrations or attempt publishing
Login not approved in browserSecure OAuth approval is still pendingStop and ask the user to approve the connection in the browserDo not enter credentials for the user
Connected but no social accounts availableNo account is ready for publishing, scheduling, replies, or analyticsReport that no social accounts are available and ask the user to connect oneDo not assume or invent an account target
User wants immediate publishingScheduling-first default is overridden by an explicit requestConfirm the target accounts from list_integrations, then publish only to those accountsDo not publish to unconfirmed accounts

Troubleshooting guidance derived from the source workflow; no runtime test results claimed.

Frequently asked questions

What is the correct order for connecting a Codex MCP server?

Run codex mcp add to register the server, then codex mcp login and pause for the user to approve Secure OAuth in the browser. Never enter credentials on the user's behalf. Then run codex mcp list to confirm the connection before calling list_integrations.

How do I check which social accounts are available after connecting?

After the connection is confirmed, call list_integrations and report which social accounts are available. If no accounts are available, stop and ask the user to connect an account rather than attempting to publish or schedule.

Should the agent publish immediately or use scheduling by default?

Prefer scheduling over immediate publishing unless the user explicitly asks to publish now. This keeps the default action reversible and reviewable before anything goes live.

What should I do if the server does not appear as connected?

If codex mcp list does not show the server as connected, do not continue to list_integrations. Re-check registration, complete the browser approval step, and verify again. If login was not approved, the connection is not complete.