Check Codex MCP access before a task
Check Codex MCP access in two places: the configured server list and the session that will use it. A server name in a configuration file does not prove that authentication works or that the account has the intended permissions.
This guide consolidates our three MCP-check notes into one exercise. It is a proposed team verification procedure, not a claim that we tested your server or credentials. Use a sandbox account and a known non-sensitive record for the first run.
What is configured?
From the terminal, run codex mcp list. Use codex mcp --help for the commands supported by the installed version. Codex stores MCP settings in config.toml; the normal user location is ~/.codex/config.toml, with project configuration available in trusted projects. In the CLI session, /mcp shows active servers. These are separate checks: configuration establishes intent, while the session shows what connected. See the official MCP documentation.
Record the server name and whether it is local or remote. Keep tokens and environment variable values out of notes and screenshots. If a server is missing, inspect the configuration used by this session before changing credentials. If it is present but disconnected, check its startup or authentication error.
How do you prove the connection works?
Start a fresh session in the intended repository. Ask it to read one known issue or documentation page through the named MCP server, without editing files or external records. Compare the returned title and identifier with the expected record yourself. A fluent summary of another issue is a failed check.
Use a disposable test resource to check denied access as well. Have the integration owner verify that a read-only credential cannot modify it. An agent declining a request is not proof that the server would reject the operation. Do not test denial against production data.
| Observation | Next check |
|---|---|
| Server is absent | Configuration scope and installed version |
| Server is listed but disconnected | Startup error and authentication |
| Read succeeds for the wrong record | Account, tenant and resource identifier |
| Test account can write unexpectedly | Provider permissions before further use |
What belongs in AGENTS.md?
Write the intended use and the stop condition in repository instructions. For example: use the approved issue server for requirements; do not change tickets; stop if the required issue cannot be read. This tells the agent how to work. It does not remove write permissions from a credential or isolate an MCP server process. Enforce those boundaries in the provider, server and runtime configuration.
When external context is required and unavailable, stop dependent work. Continue independent local work only when it does not require guessing the missing requirements. This replaces the older advice to continue from local context whenever MCP fails.
What evidence should the next engineer receive?
Keep the result small and reproducible:
Repository and installed Codex version:
Server and configuration scope:
Expected record and observed identifier:
Read test result:
Permission check performed by integration owner:
Missing access or unresolved errors:
Then perform the code task and run the repository's normal checks. An MCP connection proves access, not code correctness. Repeat the connection check when credentials, configuration or the relevant client changes, rather than attaching it to every spelling fix. The broader CLI workflows guide covers the edit and review loop.
Editorial update
Updated 20 September 2026: consolidated three overlapping access checks, removed unrelated release markers, and separated instruction guidance from permission enforcement.