MCP (Model Context Protocol) servers give an agent callable tools. To use one, make the server reachable through one of three supported paths—remote HTTP from OpenAI, HTTP from the session environment, or a local stdio process—then configure the agent, review its discovered tools, and approve or restrict calls. The right path depends on where the server runs and which data or actions it can access.
Choose the MCP connection that matches your deployment
MCP separates the client (your agent) from a server that publishes tool definitions and executes calls. The agent first discovers the tools, then selects a tool when your task requires it. Connection origin and transport are related but not identical:
| Connection | Where the server runs | What must be true |
|---|---|---|
| Remote HTTP, service origin | OpenAI-managed infrastructure | The server is reachable from OpenAI over HTTP. |
| HTTP, environment origin | Your session environment | The environment is available to the agent and can reach the HTTP endpoint. |
stdio |
Your session environment | An executable command is available; configure an absolute working directory (cwd). |
Use a provider-hosted remote server for a service you trust and want OpenAI to reach directly. Use environment HTTP when the endpoint is private to the runtime. Use stdio for a local process, development server, or a tool that should never be exposed publicly.
Add an MCP server to Codex
Codex CLI and the supported IDE surface share their MCP configuration. Adding a server once makes it available in both surfaces.
Recommended Free Tools
-
Add the OpenAI Developer Docs server from the command line
codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp codex mcp listThe second command should list
openaiDeveloperDocs. If it does not, check that you are running the same Codex installation and user profile in which you added the server. -
Or edit the shared configuration directly
[mcp_servers.openaiDeveloperDocs] url = "https://developers.openai.com/mcp"Place this block in
~/.codex/config.toml, then restart Codex or start a new session so it reloads the file. The OpenAI MCP endpoint is documented at developers.openai.com/mcp. -
Ask for a task that needs the server
Once the server is listed, give Codex a request that requires documentation lookup. Codex can inspect the published tool descriptions and call the appropriate tool. Keep approval enabled while you learn what each tool sends and returns.
Use MCP with ChatGPT agent mode
ChatGPT connects to remote MCP servers; it does not directly launch a process on your laptop. A private, on-premises, or developer-machine server therefore needs a secure tunnel that gives OpenAI a reachable endpoint without publicly exposing the process. OpenAI’s Help Center describes Secure MCP Tunnel for this situation.
Custom MCP apps and full MCP support are rolling out in beta for ChatGPT Business and Enterprise/Edu workspaces. Administrators control developer mode, publication, and access. ChatGPT agent mode does not use custom apps, while deep research can use custom apps for read and fetch actions. Verify the current workspace controls before designing a production workflow because availability can change during the rollout.
Practical ChatGPT checklist
- Confirm that your server is remote HTTP or exposed through Secure MCP Tunnel.
- Have a workspace administrator enable the required developer mode or app access.
- Start with read-only tools and inspect every requested input.
- Do not assume a local
localhostURL is reachable from ChatGPT.
Connect a remote MCP server through the Responses API
The Responses API represents an MCP server as a tool with type: "mcp", a label, and a URL. You can narrow the server’s surface with allowed_tools and select an approval policy with require_approval. The API lists the server’s tools first and returns an mcp_list_tools output item before any tool call.
const resp = await client.responses.create({
model: "<current-compatible-model>",
tools: [{
type: "mcp",
server_label: "dmcp",
server_url: "https://dmcp-server.deno.dev/mcp",
require_approval: "never",
allowed_tools: ["roll"]
}],
input: "Roll 2d4+1"
});Replace the example model, server URL, and tool name with values from your server. Treat require_approval: "never" as an explicit risk decision, not a convenience default; it allows calls without a confirmation step. If the server exposes many tools, an allow-list makes accidental invocation less likely.
Understand the discovery response
On the first request, look for the mcp_list_tools item. It confirms that the endpoint responded and shows the names and schemas the model can use. A missing discovery item usually means the endpoint, authentication, network route, or protocol handshake failed before a tool could run.
Use the current URL fields
For models released after September 1, 2026, the guide marks connector_id as deprecated. Use server_url for a remote MCP server. For a local MCP server reached through Secure MCP Tunnel, use the applicable tunnel_id configuration instead. Compatibility details are volatile, so check the live guide when upgrading models or SDKs.
Configure MCP in the Agents API
The Agents API distinguishes where the connection originates from the transport itself. Choose one of these arrangements:
| Configuration | Origin and transport | Deployment implication |
|---|---|---|
| Service HTTP | connection_origin: "service" |
OpenAI makes the request; the server must be reachable from OpenAI. |
| Environment HTTP | connection_origin: "environment" |
The session environment makes the request and must have network access. |
| Local process | stdio |
Provide an executable command and an absolute cwd; arguments are optional. |
The anonymous OpenAI Docs MCP example uses HTTP and https://developers.openai.com/mcp. For a local server, make the command deterministic, use an absolute working directory, and ensure the process writes protocol traffic to standard output rather than logging unrelated text there.
Approvals, permissions, and trust boundaries
By default, OpenAI requests your approval before data is shared with a connector or remote MCP server. Keep that behavior while evaluating a server. Approval is not merely a user-interface prompt: the data sent to a tool can include portions of the conversation, files, URLs, or credentials you deliberately supplied to the agent.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteRestrict what the model can call
- Use
allowed_toolsto expose only the operations required for the task. - Prefer read-only or search tools during initial testing.
- Require confirmation for writes, deletes, messages, purchases, or configuration changes.
- Separate servers by trust level instead of combining unrelated administrative tools.
Vet the server itself
Prefer an official server hosted by the service provider, such as a provider-hosted Stripe server, over an untrusted proxy. Read the tool descriptions, authentication requirements, retention policy, and write behavior. ChatGPT’s guidance warns that unsafe or untrusted MCP servers can increase exposure to prompt injection and other security risks. A malicious tool description can try to redirect the model, request secrets, or disguise a write operation as a harmless lookup.
Make approvals auditable
Record which server, tool, arguments, and user approval were involved in sensitive operations. If you later switch to automatic approval, retain the same logs and narrow the allow-list first. Never place a broad secret such as an unrestricted API key in a tool argument when a scoped credential is available.
A repeatable setup and debugging procedure
-
Classify the server
Write down whether it is public remote HTTP, private HTTP in the runtime, or a local executable. This determines the required connection origin.
-
Verify reachability outside the model
From the intended origin, check DNS, TLS, authentication, and the MCP endpoint path. A URL that works in your browser may still be unreachable from OpenAI, and a server bound only to
127.0.0.1will not be reachable remotely.Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesSpecial offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Discover tools with approvals on
Run a harmless request and inspect the
mcp_list_toolsoutput. Confirm names, input schemas, and whether a tool can modify data. -
Reduce the exposed surface
Set
allowed_toolsor the equivalent Agents API restriction. Remove tools that are not needed for the workflow. -
Test one deterministic call
Use fixed inputs and capture the complete response, including errors and approval events. Only after this succeeds should you add model-generated arguments or parallel calls.
-
Move to production controls
Use scoped credentials, server-side authorization, timeouts, rate limits, structured logs, and a review path for write actions. Re-test after changing the model, SDK, tunnel, or server version.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Troubleshoot common failures
| Symptom | Likely cause | Fix |
|---|---|---|
| No server appears in Codex | Wrong profile, malformed TOML, or stale session | Run codex mcp list, validate the block in ~/.codex/config.toml, and start a new session. |
| ChatGPT cannot connect to a local URL | ChatGPT requires a remote MCP endpoint | Deploy the server remotely or use Secure MCP Tunnel; do not expose an unauthenticated port. |
Responses returns no mcp_list_tools |
Endpoint, TLS, authentication, or protocol handshake failure | Test reachability from the configured origin, verify the exact MCP path, and inspect server logs. |
| Tool is never selected | It is not allowed, its description is ambiguous, or the task does not require it | Check allowed_tools, improve the server’s schema and description, and issue a narrowly worded test request. |
| Approval appears unexpectedly | Default approval policy is active or the tool is classified as sensitive | Review the arguments and keep approval enabled unless you have documented why automatic approval is safe. |
stdio process exits immediately |
Missing executable, relative cwd, or non-protocol output on stdout |
Use an absolute command and cwd, verify environment variables, and send diagnostics to stderr. |
| Calls time out or return intermittent errors | Cold starts, overloaded server, upstream limits, or long-running work | Add sensible client timeouts and retries where the operation is idempotent, reduce payload size, and expose asynchronous jobs for lengthy tasks. |
Performance, reliability, and cost decisions
Tool discovery adds a round trip before the first call, so keep the published tool catalog focused. Large schemas consume context and make selection less reliable; split unrelated capabilities across servers or expose a small allow-list. For remote HTTP, place the server close to its upstream dependencies and reuse connections. For stdio, avoid spawning a new process for every request when the client supports a persistent session.
Retries should be operation-aware. Retrying a read is usually safe; retrying a payment, deletion, or message can duplicate the action unless the server supports idempotency keys. Set an upper bound for total wait time and return a clear partial-result state when an upstream service is unavailable.
MCP itself does not define a universal price. Your costs come from the model/API usage, the server or upstream service, hosting, tunnel, and any per-call operation fees. Track tool-call counts and payload sizes separately from model tokens so an expensive server action is visible in billing and capacity reports.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup: use ScreenshotNeo from an agent
If your agent’s job is to collect website screenshots, ScreenshotNeo is a website screenshot API and MCP server for developers. It accepts a URL and returns a PNG, JPEG, WebP, or PDF. Before capture it accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. See ScreenshotNeo and the API documentation.
Use its MCP server with Claude, Cursor, or another MCP client, or call the API directly from a tool your agent controls:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Its 63 options cover full-page and selector captures, dark mode, device presets, arbitrary viewports, retina scale, PDF paper and page settings, HTML/CSS rendering, custom JavaScript, clicks, waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, configurable caching, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting, and an OpenAPI specification. Existing parameter names used by other screenshot APIs also work, which can simplify migration.
There is a free allowance of 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is on every plan, and annual billing provides two months free. Create a free ScreenshotNeo account to get started.
What to verify before production
- The server’s network origin and authentication are documented.
- Tool schemas identify read versus write behavior.
- Approval is enabled for sensitive operations.
- Only necessary tools are exposed.
- Logs capture server, tool, arguments, result status, and approval.
- Retries cannot duplicate non-idempotent actions.
- Workspace, model, tunnel, and MCP client versions are pinned or tested together.
Frequently Asked Questions
What does the mcp_list_tools item mean?
It is the discovery result returned before tool calls. It shows that the endpoint responded and tells the model which tools and input schemas are available.
Can an MCP server send data back to my agent?
Yes. Tool results become part of the agent’s context, so review the server’s data handling and avoid sending secrets or unnecessary personal information.
Should every MCP server expose write tools?
No. Publish only the operations required by the workflow; keep administrative or destructive actions on a separate, approval-protected server.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
