Codex .codex/config.toml: share Sume's MCP entry per project

You can put Sume's MCP entry in a project's .codex/config.toml so the whole repo shares it, but Codex only reads that file for trusted projects. For everything else the entry has to live in your user file at ~/.codex/config.toml. Keep the URL in the shared file and any credential out of it.

The config locations come from the Codex MCP docs (read 2026-10-02). The Sume entry is from the MCP quickstart.

Where does Codex read MCP settings?

By default, in ~/.codex/config.toml. For project-scoped settings, in .codex/config.toml inside the project, and the page says this applies to trusted projects only. Servers are tables named [mcp_servers.<server-name>]. A streamable HTTP server takes a required url, plus optional bearer_token_env_var, http_headers and env_http_headers. Timeouts are startup_timeout_sec (default 10) and tool_timeout_sec (default 60), and you can narrow tools with enabled_tools and disabled_tools, where the deny list applies after the allow list.

The CLI commands on the page are codex mcp list, codex mcp login <server-name>, codex mcp logout <server-name> and codex mcp add <name> -- <command>; the add example there is for a STDIO server, so for a remote URL you edit the TOML.

What does the Sume entry look like?

A remote server needs only the URL for the OAuth path. Sume's quickstart says to point a streamable HTTP MCP server at https://mcp.sume.com/mcp, run that client's OAuth login for the configured name, and the client discovers Sume's protected-resource metadata and sends you through https://mcp.sume.com/oauth/authorize to consent.

After you save the file, run the login for the name you chose, then ask Codex to call tools_list. With the default read-only consent you will see read-only tools.

[mcp_servers.sume]
url = "https://mcp.sume.com/mcp"
# Optional: only expose read tools to this project
# enabled_tools = ["tools_list", "jobs_list", "catalog_list"]

# API-key path instead of OAuth: read the key from the environment
# bearer_token_env_var = "SUME_API_KEY"

What should go in the shared file and what should not?

Put the table name and url in .codex/config.toml. Put enabled_tools there too if the team wants a project to stay read-only; that is a configuration choice and travels with the repo. Do not put a key in it. bearer_token_env_var names an environment variable, so the file carries only the variable name, and each person supplies the value. Sume's docs say an OAuth token is not an API key and that keys which show up in logs or chat should be rotated.

Remember how Sume's scopes interact with this: OAuth sessions are read-only unless the person turned Write on at consent, and a key sees everything. An allowlist in the TOML is a second layer on top, not a replacement, because Sume itself returns insufficient_scope for mutating calls on a read-only session.

If a project needs generation, say so in the repo README rather than loosening the file: tell people to sign in with Write on, to run paid calls with dry_run first, and to pass max_spend_usd when they want a cap. That keeps the shared config conservative and the decision with the person who pays.

Why is my project entry ignored?

The usual cause is trust. The docs limit project-scoped settings to trusted projects, so an untrusted checkout silently falls back to your user settings. If the entry does not appear in codex mcp list, check that the project is trusted first, then the TOML table name and the URL. A second cause is a misspelled key: the field is url, and the table must be mcp_servers, plural.

Timeouts are the other thing to keep in mind when you share a file. The default tool_timeout_sec of 60 is already above Sume's 55-second jobs_wait cap, so you rarely need to raise it; see the timeout post for Codex.

A last practical point is how you verify the shared setup after a teammate pulls it. Have them open the project, confirm the project is trusted, run codex mcp list, then codex mcp login sume, and ask Codex to call mcp_health. Sume's docs say that call confirms the endpoint, the auth source and the safety posture, which makes it the quickest way to see that the shared entry works for their account and not just yours. If it reports read-only visibility, that is the default OAuth grant at work, and each person can opt into Write on their own consent page without touching the shared file.