MCP setup and connection checks

Back to the Codex learning hub

Goal and preparation

Lessons and resources mentioned here: Installation

MCP lets clients invoke tools and receive context. Capabilities depend on the server: connecting documentation does not grant GitHub or local browser access. OpenAI Docs MCP searches and retrieves documentation without calling the OpenAI API on your behalf. Use it to practice retrieval acceptance; a later service that writes data needs its own tool and Permission review.

Step 1: Choose transport and configuration location

This exercise uses only Streamable HTTP. A website homepage is not necessarily its MCP endpoint; use the provider's documented address, and do not paste a STDIO command into a URL field.

Desktop, CLI and IDE clients on the same Codex host share MCP configuration. The default user file is ~/.codex/config.toml: .codex under the user directory on Windows and the home directory on macOS/Linux. Honor an existing custom CODEX_HOME. Trusted projects can also use .codex/config.toml; this exercise uses the user configuration instead of editing an unfamiliar project. See config.toml.

Step 2: Inspect existing entries before adding

codex mcp list

Run the command in Windows PowerShell, macOS Terminal or a Linux terminal, outside the interactive codex session. Check for codexLearningDocs before adding it; inspect a same-name entry instead of overwriting it. You may reuse an existing working entry for the same official endpoint, recording that fact and preserving it during cleanup. Lists can contain private service URLs, so avoid publishing the entire output.

Before adding, open the actual user config.toml in an editor and save a dated backup without replacing an older backup. If it does not exist, record that state without creating an empty file. Make one change and preserve the diff. Backups may contain sensitive values; keep them locally outside Git. At cleanup, remove only the new entry rather than overwriting settings another task may have added since the backup.

codex mcp add codexLearningDocs --url https://developers.openai.com/mcp
codex mcp get codexLearningDocs

Expect get to show the name, HTTP transport and exact official URL. This proves only that configuration was saved, not reachability, tool discovery or a successful query. Tool counts can change; do not copy a fixed count from a tutorial. A zero exit from a management command is not retrieval evidence. If a command is absent, inspect codex mcp --help and the CLI update instructions.

Equivalent desktop and IDE steps

Without CLI, open Settings → MCP servers → Add server on desktop, enter codexLearningDocs, select Streamable HTTP, paste the same endpoint, save and choose Restart. In the IDE gear menu choose MCP servers → Add server with the same fields, save and Restart extension. Follow the equivalent steps in your available Windows, macOS or Linux client. If a Linux preview or version lacks this UI, use CLI without treating the missing button as a service failure.

[mcp_servers.codexLearningDocs]
url = "https://developers.openai.com/mcp"

The snippet represents the same configuration: choose CLI, UI or manual editing, not all three. Adding through CLI and pasting the same TOML table again can create an invalid duplicate table. For manual editing, merge only that section and restart the client. ChatGPT web and mobile do not read your computer's local config.toml; hosted capabilities use Plugins. Local success does not configure the phone.

Step 3: Inspect tools and retrieve a source

/mcp

In a fresh desktop, CLI or IDE task/session, enter /mcp in the Codex composer to inspect the server and tools; it is not a shell command. You can also check MCP servers settings and observe tool activity in the new task. If authentication is requested, verify the public endpoint first. Other OAuth services may require Authenticate or codex mcp login with their name; do not add an arbitrary API key for this public service.

Use the codexLearningDocs MCP tools to find the official AGENTS.md instructions.
Read the relevant page and explain global versus project rules in three bullets.
Include the source URL and the section you checked.
If the MCP tools are unavailable, report that limitation instead of answering from memory.
Do not edit files or call paid APIs.

If reusing a server, replace the name in the prompt. Observe a search or retrieval tool activity and open the cited official page to verify that the section supports the explanation. Response wording can vary; acceptance concerns tool evidence, URL and content, not fixed wording or tool names. A correct answer without MCP is a general answer and does not complete this connection exercise.

Step 4: Disable, retest and remove

For the negative case, change an existing enabled value to false; add enabled = false once only when that key is absent. Never duplicate the key or table. The client disable control is also valid. Save, restart, then use /mcp and actual tool activity in a fresh desktop, CLI or IDE task/session to confirm the tools are unavailable. Old conversation text is not fresh retrieval. Restore the prior value, or remove only the key you added, restart and repeat the read.

codex mcp remove codexLearningDocs
codex mcp list

After removal, a fresh task should no longer list the new entry. This does not remove other servers, delete documents or revoke unrelated OAuth grants. Skip removal for a reused entry. If configuration was never changed, record that. For authenticated services, remove and logout serve different purposes; check MCP troubleshooting instead of clearing every connection.

Failures and completion criteria

For a missing server, check configuration scope, name, enabled state and restart. For TOML parse errors, inspect duplicate tables and quotes without resetting the whole file. If configuration is correct but connection fails, verify the full URL, host network and service state, preserving a redacted error. If an answer lacks a source, request and verify the page. These four failures have different evidence; broadly relaxing permissions rarely explains them.

Record the actual client version, saved configuration, one sourced tool result and disable/removal of your added entry. Windows isolated-configuration and public-service protocol tests may be recorded separately, but do not establish desktop UI, macOS, Linux or your model-task execution. Unoperated surfaces are documented from official sources. Save results with the Connection template and continue to troubleshooting when needed.

Back to the Codex learning hub

Read the full description

Configuration to Handshake to Tool result

• AI tools
• Tutorials
• Codex