Skip to content
Sign inGet started
Sign inCreate account
Documentation · Codex

Connect Codex to MCP servers through Toolstile

On this page

Codex talks to Toolstile as a single streamable HTTP MCP server. Register it with codex mcp add toolstile --url 'https://toolstile.com/mcp', run codex mcp login toolstile to approve it in your browser, and pick the Toolstile workspace Codex should use. Codex sees no tools until the agent it created is granted access in that workspace.

The entry lands in ~/.codex/config.toml. The Codex CLI, IDE extension and desktop app read the same file, so one entry covers all three on that machine.

What you need

  • Codex installed and signed in.
  • A Toolstile account with at least one MCP connection in the target workspace. Getting started walks through the first one, and integrations has provider-specific notes.
  • A browser for the OAuth approval, on this machine or the one you are working from.

Toolstile's managed service connects only to public HTTPS MCP servers. Servers you run through Codex as stdio commands (codex mcp add <name> -- <command>) stay in Codex's own configuration.

Add Toolstile to Codex

Run these two commands:

Shell
codex mcp add toolstile --url 'https://toolstile.com/mcp'
codex mcp login toolstile

The first writes a server table; the second starts OAuth. If you prefer editing the file, this is the equivalent entry in ~/.codex/config.toml:

TOML
[mcp_servers.toolstile]
url = "https://toolstile.com/mcp"

After a manual edit, still run codex mcp login toolstile. Keep a single [mcp_servers.toolstile] table; a second table with the same name is a TOML error, not a second connection.

User or project configuration. ~/.codex/config.toml applies everywhere you run Codex. Codex also reads .codex/config.toml inside a project, but only for projects you have marked as trusted. A project file is a reasonable place to share the server URL with a team. Never put credentials in it.

Sign in and choose a workspace

codex mcp login toolstile opens your browser. There:

  1. Sign in to Toolstile if asked.
  2. Select the Workspace. This authorization will use that workspace's MCP connections and operation allowance, and nothing else.
  3. Check the suggested agent and device names. Use Edit names for something like Codex (build box) if you run Codex in several places.
  4. Choose Approve, then finish any Allow connection consent screen.

Codex stores the OAuth credentials locally and uses them for later sessions.

Codex on a remote machine. The login waits on the remote machine's loopback address, so your laptop's browser cannot reach it directly. Append &device_name= plus the machine's name (for example the output of hostname -s) to the sign-in link Codex prints, then open it locally. After you approve, Toolstile shows a command to run on the remote machine to complete the sign-in. Alternatively, run npx toolstile auth login and npx toolstile mcp setup on that machine: sign-in uses a code you approve in any browser, with nothing to run afterwards. See set up a whole machine from the terminal.

Grant the agent access in Toolstile

Approval creates an agent with no MCP access. In the workspace you picked, open Devices & agents and find it. Then open Access, choose a connection, and in the agent's column set each tool to Allow, Require approval or Block. Choose Save changes.

Codex often runs with less supervision than an editor agent, which is a good reason to keep its grant narrow. Allow the reads it needs, require approval for anything that changes shared data, and block deletes. Full access (Everything, including ones added later) also covers tools the server adds in future, subject to your blocks. Team admins grant each agent individually. Details are in permissions.

A call to a tool set to Require approval returns a result saying approval is needed, with a link to Toolstile's Approvals page. After someone approves it there, Codex has to send the identical call again; approval itself runs nothing.

Confirm the setup

Shell
codex mcp list
codex mcp get toolstile

list shows configured servers and get prints the stored entry (--json gives the raw config). Inside a Codex session, /mcp shows the MCP servers that are active.

Toolstile's Test tool action can load the agent's permitted tools without executing anything. For an end-to-end check, ask Codex to do one read-only lookup with non-sensitive input, then look for the matching entry in Activity in the same workspace. Expect tool names through the gateway to differ slightly from the upstream server's names.

Codex approval settings and Toolstile grants

Codex and Toolstile each have a say, and either can stop a call.

Toolstile controls which tools reach Codex at all. Blocked or ungranted tools are left out of the tool list, and calling one by name is refused. These rules live in the workspace, so they hold on every machine where this agent is authorized.

Codex controls whether it asks you first. Each MCP server table accepts default_tools_approval_mode, with the values auto, prompt, writes and approve; writes prompts for tools that are not marked read-only. You can override a single tool under a nested tools table, and filter what Codex loads with enabled_tools and disabled_tools:

TOML
[mcp_servers.toolstile]
url = "https://toolstile.com/mcp"
default_tools_approval_mode = "prompt"

[mcp_servers.toolstile.tools.search_issues]
approval_mode = "approve"

The tool name here is a placeholder; use the names /mcp shows. Codex's filters can only narrow what Toolstile already allows. They cannot add a tool that Toolstile withholds.

Direct servers or Toolstile

Adding each provider straight into config.toml is fine for a few personal servers, and it is the only option for stdio servers or anything on a private network.

Through Toolstile, Codex holds one credential for the gateway instead of one per provider. Provider sign-in happens once in the dashboard, each Codex install is its own agent with its own grant, and you can remove one without touching the others. You can mix both approaches in the same config.toml.

Troubleshooting

codex mcp login does not open a browser, or the redirect fails. Copy the printed URL into a browser on the same machine. On a remote host, use the device_name step above. If an old login is stuck, run codex mcp logout toolstile and log in again rather than reusing an earlier sign-in link.

Login succeeded but Codex lists no Toolstile tools. The agent has no grant yet, or the grant is in a different workspace. Check Access in the workspace you approved, and confirm the connection does not show Needs sign-in or Needs attention.

Codex still shows old tools after you changed access. Start a new Codex session so it fetches the list again. Toolstile checks current grants on every call, so a removed tool fails even if Codex still lists it.

Codex is using the wrong workspace. The workspace is fixed when you approve. Switching the dashboard does not move it. Add a separate entry, such as toolstile-team, run codex mcp login toolstile-team, and pick the team workspace in that approval.

Startup times out. Codex waits 10 seconds for a server to start by default. startup_timeout_sec in the server table raises that limit; tool_timeout_sec (default 60) covers slow tool calls.

Requests stop with a quota or billing error. The workspace's monthly operations are used up or forwarding is paused. A workspace owner can check Usage & billing.

More cases, including unavailable shared accounts, are in troubleshooting. Include your Codex version and the exact error if you contact support.

Remove Toolstile from Codex

Shell
codex mcp logout toolstile
codex mcp remove toolstile

logout deletes the stored OAuth credentials and remove deletes the entry. Neither revokes the agent in Toolstile; do that with Remove agent under Devices & agents.

OpenAI documents these commands in its Codex MCP guide and command reference.