← Back to Blog

2026-09-26 • 7 min read • Connect

How to Connect an MCP Server to Codex

Connect a hosted MCP server to Codex in the ChatGPT desktop app, CLI, or IDE extension, check that its tools load, and ask your first grounded question.

To connect an MCP server to Codex, you need the server's HTTPS URL. Add it in the ChatGPT desktop app under Settings, then MCP servers, or run codex mcp add <name> --url <url> in the Codex CLI. Then start a new session and type /mcp to confirm the tools loaded. MCP Studio by Appa Tools builds that server from your docs, a GitHub repository, or files without any code.

By the end of this guide, Codex will answer from your own material. You will have checked the tool list, asked a question you know the answer to, and seen Codex cite the page it came from.

What Codex needs from an MCP server

Codex is OpenAI's coding agent. It runs in the ChatGPT desktop app, in the terminal as the Codex CLI, and inside your editor as an IDE extension. All three read the same MCP configuration, so you add a server once and every surface can use it.

A server you reach by URL. Codex calls this kind of server a Streamable HTTP server. It lives at an address on the internet rather than running as a program on your laptop. MCP Studio hosts yours, so there is nothing to install or keep running.

Tools Codex can call. When a session starts, Codex asks the server what it can do and gets back a list of tools, such as search_docs or ask_question. During the conversation it calls them whenever the work needs your material.

Guidance that travels with the server. Codex reads the instructions a server sends when it connects and uses them alongside its tools. An MCP Studio server sends guidance on grounding answers in the passages it returns and citing the page each fact came from, so you do not have to repeat that in every prompt.

Build the server in MCP Studio

Take a real example. Harborline is a ferry operator with a public brand kit: colors, voice rules, the people it writes to, customer facts like terminals and refunds, and a ready-made welcome email. You want Codex to build a booking page or an email template in that palette and voice without pasting the kit into every session.

  1. Open the MCP Studio wizard. You do not write any code, and the wizard takes about a minute.
  2. Name it for the job. Harborline brand tells you later what the server is for.
  3. Add the source. Paste a documentation URL, a website, or a GitHub repository, or upload a PDF, a spreadsheet, or an image. For Harborline, that is the brand kit repository.
  4. Choose the tools. Pick at least three. Search and question answering cover most coding sessions, and the tool selection guide explains the rest.
  5. Deploy, then copy the server URL from the setup page. It looks like this:

https://appatools.com/mcp-studio/api/mcp/your-server-name

The endpoint exists straight away, and indexing continues in the background. Give a large site a few minutes before you judge the answers.

Add the server to Codex

Use whichever surface you work in. They share one configuration, so one of these is enough.

In the ChatGPT desktop app:

  1. Open Settings, then select MCP servers.
  2. Select Add server.
  3. Enter a name, choose Streamable HTTP, and paste the server URL.
  4. Save the server, then select Restart.

In the Codex CLI:

codex mcp add harborline --url https://appatools.com/mcp-studio/api/mcp/your-server-name

In the IDE extension: open the gear menu, select MCP servers, then Add server, and fill in the same name and URL. Save, then select Restart extension.

Or edit config.toml directly. Codex stores servers in ~/.codex/config.toml:

[mcp_servers.harborline]
url = "https://appatools.com/mcp-studio/api/mcp/your-server-name"

Connect a private server

If the material is confidential, make the server private in MCP Studio and create an access token in the server's Access panel. It starts with mcps_live_. Codex reads it from an environment variable you name:

[mcp_servers.harborline]
url = "https://appatools.com/mcp-studio/api/mcp/your-server-name"
bearer_token_env_var = "HARBORLINE_MCP_TOKEN"

Set HARBORLINE_MCP_TOKEN to the token in the environment Codex starts from. Treat it like a password, and keep it out of any file you commit. A token works for one server only. The private servers guide covers creating and revoking tokens.

Check that it works

Start a new session. Codex connects to its servers when a session starts, so a chat that was already open will not pick up a server you just added.

Type /mcp. Your server should appear with its tools listed. In the terminal, codex mcp list shows every configured server.

Ask something you know is in the source. For Harborline:

Give me a two sentence elevator pitch for my company using the Harborline MCP server.

Codex calls the server's tools, then writes from the passages it got back. Compare the specifics rather than the tone: that Harborline runs ferries, a phrase from the voice rules, a color name like Hull Navy. Each passage carries a link to the page it came from, so you can open it and check.

Then ask something the source does not cover. When nothing in your content is a real match, the server says so first, and Codex passes that on instead of filling the gap from general knowledge.

You: What is Harborline's parental leave policy?

Codex: The Harborline server does not have anything on parental leave. Its content covers the brand colors, voice, audiences, and customer facts. You would need to add the HR handbook as a source.

One known answer and one deliberate miss tell you the connection is doing its job.

If the tools do not appear

The server is missing from /mcp. Start a new session or restart the extension, then check that the URL contains /api/mcp/. The wizard page and the dashboard are not MCP addresses.

It needs a login or returns unauthorized. The server is private and the token is missing, revoked, or belongs to a different server. Create a new one in Access and update the variable.

Tools load but answers are thin. Indexing may still be running, or the question uses different words than the source. The wrong information guide walks through both.

Frequently asked questions

Does Codex support remote MCP servers?

Yes. Codex connects to MCP servers by URL, which it calls Streamable HTTP servers, as well as to local servers started by a command. The ChatGPT desktop app, the Codex CLI, and the IDE extension all support them and share the same configuration.

Do I need to write code to build an MCP server for Codex?

No. MCP Studio builds and hosts the server from a documentation site, a GitHub repository, or uploaded files. You pick the tools in a wizard, deploy, and paste the URL into Codex.

Can I use the same MCP server in Codex, Claude, and Cursor?

Yes. The server URL is the same for every client, so one server can back Codex, Claude, Cursor, and Windsurf at once. Usage from every client counts toward the same account allowance.

Does ChatGPT on the web use my Codex MCP servers?

No. ChatGPT on the web does not read your local Codex configuration and uses plugins for its tools instead. The steps in this guide apply to the ChatGPT desktop app, the Codex CLI, and the IDE extension.

How do I connect a private MCP server to Codex?

Make the server private in MCP Studio, create an access token, and set bearer_token_env_var in Codex's config.toml to the name of an environment variable that holds it. Codex sends the token with every request, and a server without it refuses the connection.

Is it free to try?

Yes. The MCP Studio free tier includes 3 servers, 2 sources per server, and 50 MCP requests a month per account, which is enough to connect Codex and test real questions before you decide on a plan.

Connect Codex to your docs with MCP Studio

Build a server from one source, paste its URL into Codex, and ask a question you already know the answer to. The wizard takes about a minute and needs no code. Create your server in MCP Studio.

Where to go next