# Running coding agents on a corporate network

URL: https://developertoolkit.ai/en/org/corporate-environment/
Description: Get Claude Code, Codex and Cursor working behind a corporate proxy, TLS inspection, SSO and an egress allowlist, delivered by MDM and proven by a smoke test.

Running Claude Code, Codex or Cursor inside a corporate network takes four controls, set once per organization: a proxy route the tools trust through TLS inspection, an egress allowlist, sign-in pinned to the company tenant, and MCP connections to internal systems that authenticate as the user. Each ships through managed settings or MDM and is proven by a smoke test.

This page is for the CTO, platform lead or IT owner who has approved a pilot and now has 30 managed laptops where nothing connects. The agent fails with `self-signed certificate in certificate chain`, the MCP server for Jira never finishes its OAuth login, and security wants to know which hosts the tools talk to before opening the firewall. What follows is the order to fix those in, per tool, and how to prove each fix holds on every machine.

## What a working corporate setup gives you

- A managed-settings file and a Codex `requirements.toml` that set the proxy, the corporate root CA and the allowed sign-in, delivered by MDM instead of per-developer shell edits.
- An egress allowlist derived from your own proxy logs, with the hosts Anthropic documents as a starting point.
- MCP connections to Jira and Confluence that log in as the user through OAuth, and to GitHub with a per-user scoped token, so the agent can reach only what the user can.
- A smoke-test script that says PASS or FAIL for each control on a freshly enrolled laptop, so nobody reads config files by hand.
- A failure table for the errors the pilot will actually hit, with the fix for each.

What to allow (models, tools, MCP servers, permission floors) is a policy question covered in [enforcing one policy across every coding agent](/en/org/managed-policy/). Where the model runs (Bedrock, Google Cloud, a gateway, zero data retention) is covered in [where the model runs](/en/org/model-hosting/). This page makes the tools work on your network once those decisions are made.

## What does a coding agent need from the corporate network?

Four controls, in the order they fail on day one:

| Control | Symptom when missing | Owner | Where it is set |
| --- | --- | --- | --- |
| **Proxy route and TLS trust** | Timeouts; `ECONNREFUSED`; Claude Code stops at launch when the proxy URL has no scheme. Then `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, `self-signed certificate in certificate chain`, Codex "Failed to read CA certificate file" | Network team, Security / PKI | Proxy variables plus the OS trust store and a per-tool CA variable, delivered by managed settings or MDM |
| **Egress allowlist** | One feature fails while the rest works (plugins, connectors, the updater) | Network team | Proxy or firewall policy |
| **Sign-in** | Developers sign in to a personal account | Identity team | Managed login settings |
| **MCP identity** | MCP OAuth callbacks never complete; a server connects with a shared token | Identity team | OAuth client registration; per-user tokens |

Fix them in that order, route before trust. A CA problem looks like a proxy problem until the route works, and an OAuth problem looks like a CA problem until TLS works.

## Configure the proxy and the corporate CA in each tool

The three tools use different trust stores, so one `NODE_EXTRA_CA_CERTS` export does not fix all of them. Claude Code is a Node application, Codex is a Rust binary with its own CA variable, and Cursor is an Electron app.

**Claude Code**

    Claude Code reads `HTTPS_PROXY`, `HTTP_PROXY` and `NO_PROXY` (lowercase variants too). It trusts its bundled Mozilla CA set **and** the operating system store by default, so a TLS-inspection root installed in the OS store usually works with no extra setting. The OS store needs the native installer or Node 22.15 or later on npm installs; otherwise add the root with `NODE_EXTRA_CA_CERTS`.

    Put the variables in the `env` block of managed settings, not in a shell profile. Background agents (`claude agents`, `--bg`) run under a per-user supervisor process that does not inherit your shell, so a shell export reaches them only by accident. Anthropic's [network configuration docs](https://code.claude.com/docs/en/network-config) say settings are the only configuration that reaches every background session.

    ```json
    // managed-settings.json
    {
      "forceLoginMethod": "claude-ai",
      "forceLoginOrgUUID": "YOUR_ORG_UUID",
      "env": {
        "HTTPS_PROXY": "http://proxy.corp.example:8080",
        "NO_PROXY": "localhost,127.0.0.1,.corp.example",
        "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/corp-root-ca.pem"
      }
    }
    ```

    Deploy it through the claude.ai admin console, an MDM profile, or the system path (`/Library/Application Support/ClaudeCode/` on macOS, `/etc/claude-code/` on Linux and WSL, `C:\Program Files\ClaudeCode\` on Windows). `YOUR_ORG_UUID` is your claude.ai organization ID; only a managed source enforces `forceLoginOrgUUID`. Proxies that require client certificates use `CLAUDE_CODE_CLIENT_CERT` and `CLAUDE_CODE_CLIENT_KEY`. The tool-specific detail is in [proxy and VPN configuration for Claude Code](/en/claude-code/team/proxy-configuration/).

**Codex**

    Codex does not read `NODE_EXTRA_CA_CERTS`. It reads the CA bundle from `CODEX_CA_CERTIFICATE`, falls back to `SSL_CERT_FILE`, and uses the system roots when neither is set (per `codex-rs/http-client/src/custom_ca.rs`, checked 2026-09-26). It reads the standard proxy variables, and in codex-cli 0.157.1 the `system_proxy_fallback` feature (stable, on) lets it fall back to the operating system's proxy settings, which arrived with PAC/WPAD support in 0.143.0.

    ```bash
    # Delivered by MDM or the managed shell profile, not typed by developers
    export HTTPS_PROXY=http://proxy.corp.example:8080
    export NO_PROXY=localhost,127.0.0.1,.corp.example
    export CODEX_CA_CERTIFICATE=/etc/ssl/certs/corp-root-ca.pem
    ```

    Pin sign-in in the admin constraints file, which users cannot override:

    ```toml
    # /etc/codex/requirements.toml
    allowed_login_methods = ["chatgpt"]
    allowed_chatgpt_workspaces = ["YOUR_WORKSPACE_ID"]
    ```

    `YOUR_WORKSPACE_ID` is your ChatGPT Business or Enterprise workspace ID. Both keys are in `config_requirements.rs` (checked 2026-09-26); the rest of the file is covered in [managed policy](/en/org/managed-policy/) and [Codex enterprise governance](/en/codex/team/enterprise-governance/).

**Cursor**

    Cursor is an Electron app with its own network stack, so configure it through Cursor's network documentation and prove the result with the smoke test and the proxy logs below rather than by reading its settings. Two things hold whatever Cursor's own settings are:

    - MCP servers Cursor launches with `npx` are Node processes. Node reads `NODE_EXTRA_CA_CERTS` at startup, so set it in the environment Cursor is launched from (the MDM-managed login environment, not a terminal export).
    - Whether an MCP server honors `HTTPS_PROXY` depends on that server's HTTP client. Test each stdio server behind the proxy before you approve it, or prefer the vendor's remote HTTP server, which Cursor connects to directly.

    Because no Cursor host list could be verified, derive Cursor's allowlist from proxy logs with the prompt in the next section; include `Cursor` and its Electron helper processes in the process filter. Team privacy and admin controls are in [Cursor privacy and security](/en/cursor-ide/team/privacy-security/).

  Never set `NODE_TLS_REJECT_UNAUTHORIZED=0` to get past a certificate error. It turns off validation for every connection the process makes, including the ones your TLS inspection exists to watch, and it fails any security review. Fix the trust store instead. Claude Code does not support SOCKS proxies (checked on Claude Code 2.1.283), and for NTLM or Kerberos proxy authentication Anthropic recommends an LLM gateway that supports the method.

## Which hosts do you allowlist?

Start from the vendor's list and finish from your own proxy logs. Anthropic publishes the Claude Code list in its [network access requirements](https://code.claude.com/docs/en/network-config#network-access-requirements); the hosts most pilots need are:

| Host | Needed for |
| --- | --- |
| `api.anthropic.com` | Model requests (not on Bedrock, Google Cloud or Foundry routes, apart from the WebFetch safety check) |
| `claude.ai`, `claude.com`, `platform.claude.com` | Sign-in and OAuth token refresh |
| `mcp-proxy.anthropic.com` | MCP connectors configured in claude.ai, which route through this host |
| `downloads.claude.ai` | Native installer, auto-updater, plugin executables |
| `registry.npmjs.org` | `npx`-launched MCP servers and plugin dependencies, unless you mirror npm |
| `github.com` | Plugin marketplaces hosted on GitHub |

For Codex and Cursor there is no vendor list we could verify on 2026-09-26, so derive theirs the same way you check Claude's: run a pilot machine through a normal day with the proxy in log-only mode, then turn the log into the allowlist. The prompt below does that.

**Copy-paste prompt: derive the egress allowlist from proxy logs**

```text
Read proxy-export.csv (columns: timestamp, user, process, host, port, bytes, verdict).
It covers one pilot day on laptops running Claude Code, Codex and Cursor.
1. Group by host and by process name: claude, codex, Cursor and every
   process whose name starts with Cursor (its Electron helpers), node, npx, git.
2. For each host, say which tool and which feature most likely needed it
   (model API, sign-in, MCP server, package registry, updater, telemetry).
3. Mark hosts that carry only optional telemetry separately, so we can decide
   whether to block them.
4. Output a table: host, process, feature, first seen, request count, keep/optional/unknown.
Do not guess: if you cannot attribute a host from the data, mark it unknown.
```

## Connect internal systems over MCP with the user's own identity

An MCP server that authenticates with the user's own credentials (an OAuth login or a per-user token) acts as the user, so the agent can reach only the Jira projects and repositories that person can already reach, and every write lands in the audit log under their name. Prefer a vendor's remote server over a local stdio package: the remote server removes a package that would otherwise run on every laptop. Both examples below are remote, but they authenticate differently. Atlassian's server signs in with OAuth as the user through your Atlassian login. GitHub's remote server authenticates with a personal access token (PAT) header, not your identity provider; browser OAuth with no token exists only on GitHub's local Docker server (per GitHub's install guides, tested on Claude Code 2.1.283).

**Claude Code**

    ```bash
    # Atlassian (Jira, Confluence): /v2/mcp is the recommended endpoint
    claude mcp add --transport http atlassian https://mcp.atlassian.com/v2/mcp
    # GitHub's remote server: PAT header, no OAuth login
    claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
      -H "Authorization: Bearer $GITHUB_PAT"
    ```

    Run `/mcp` in a session to complete the Atlassian OAuth login; GitHub connects with the token alone. The shell expands `$GITHUB_PAT` when you run the command, so the token itself is stored in the MCP config; rotate it by re-running the command. To keep the token off disk, as the PAT advice below requires, declare the server in `.mcp.json` with a variable reference instead. Claude Code expands `${VAR}` in `headers` when it loads the file, so the value comes from the MDM-delivered environment variable:

    ```json
    // .mcp.json
    {
      "mcpServers": {
        "github": {
          "type": "http",
          "url": "https://api.githubcopilot.com/mcp/",
          "headers": { "Authorization": "Bearer ${GITHUB_PAT}" }
        }
      }
    }
    ```

    For the read-only rollout weeks, use `https://api.githubcopilot.com/mcp/readonly` as GitHub's URL. If your identity provider only accepts pre-registered OAuth clients, register one and pass `--client-id` and a fixed `--callback-port` so the redirect URI matches.

**Codex**

    ```bash
    codex mcp add atlassian --url https://mcp.atlassian.com/v2/mcp
    codex mcp login atlassian
    codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT
    ```

    For GitHub, `--bearer-token-env-var` sends the PAT from the named variable as a bearer token, as GitHub's install guide for Codex does. On a remote shell or VDI where no browser can open, `codex mcp login atlassian --no-browser` prints the authorization URL and accepts the callback URL by paste. `codex mcp login atlassian --scopes <scope,scope>` requests only the OAuth scopes you list.

**Cursor**

    ```json
    // .cursor/mcp.json
    {
      "mcpServers": {
        "atlassian": { "url": "https://mcp.atlassian.com/v2/mcp" }
      }
    }
    ```

    Atlassian also publishes a plugin in Cursor's marketplace. For GitHub, GitHub's install guide for Cursor uses the same remote URL with a personal access token header.

Four corporate details the vendor pages spread across several documents:

- **GitHub PATs:** issue a fine-grained PAT per user, scoped to the pilot repositories, with a 30 to 90-day expiry, and deliver it through the OS keychain or an MDM-managed secret. Never share one token across the team: every write would land under one name, and the audit prompt below flags exactly that.
- **Atlassian:** API-token authentication must be enabled by an Atlassian admin, Jira Service Management tools work only with API tokens, and Atlassian IP allowlisting applies to the MCP server. The old `/v1/sse` endpoint stopped being supported after 30 June 2026. For Server or Data Center, the community `sooperset/mcp-atlassian` server is the usual route; see the [Atlassian MCP guide](/en/ecosystem/mcp/atlassian-mcp/).
- **claude.ai connectors** reach Claude Code through `mcp-proxy.anthropic.com` and are on by default for claude.ai-authenticated users. To keep MCP traffic on servers you approved, set `"disableClaudeAiConnectors": true` in managed settings, and allowlist servers with `allowedMcpServers` as described in [managed policy](/en/org/managed-policy/).
- **Internal systems with no vendor server** (an ERP, a SOAP service) need a thin MCP server you own. Build it with [custom MCP server development](/en/ecosystem/mcp/custom-mcp-development/) and run it the way [internal MCP servers](/en/cto-scorecard-guide/internal-mcp-servers/) describes. Scoping and scanning servers before approval is in [MCP security](/en/cto-scorecard-guide/mcp-security/).

## How do you prove the setup works on every laptop?

Nobody should verify a corporate rollout by reading config files. Run a smoke test on each newly enrolled machine, from MDM or the first-run script, and collect the output. Every line is PASS or FAIL, so a platform engineer reads a summary, not a config.

```bash
#!/usr/bin/env bash
# agent-env-smoke.sh: run as the developer on a freshly enrolled laptop.
# Needs CORP_PROXY (the proxy URL) and CORP_CA (a PEM bundle: the corporate root
# concatenated with the OS bundle, so hosts exempt from TLS inspection still verify).
set -u
: "${CORP_PROXY:?set CORP_PROXY}" "${CORP_CA:?set CORP_CA}"
fail=0
check() { if "$@" >/dev/null 2>&1; then echo "PASS  $*"; else echo "FAIL  $*"; fail=1; fi; }

# 1. Proxy route plus TLS-inspection trust, host by host
for host in api.anthropic.com platform.claude.com downloads.claude.ai registry.npmjs.org github.com; do
  check curl -sS --max-time 10 -o /dev/null --proxy "$CORP_PROXY" --cacert "$CORP_CA" "https://$host"
done

# 2. Signed in. `auth status` proves a login, not which tenant; the tenant pin itself is
#    enforced by forceLoginOrgUUID / allowed_chatgpt_workspaces, so prove those files are present.
check claude auth status
check codex login status
# macOS path: /Library/Application Support/ClaudeCode/managed-settings.json.
# Drop this line if managed settings come from the claude.ai admin console instead.
check grep -q forceLoginOrgUUID /etc/claude-code/managed-settings.json
check grep -q allowed_chatgpt_workspaces /etc/codex/requirements.toml

# 3. One real model round trip per tool, read-only
check sh -c 'claude -p "Reply with the single word OK" | grep -q OK'
check sh -c 'codex exec --skip-git-repo-check -s read-only "Reply with the single word OK" | grep -q OK'

# 4. MCP servers connect. claude mcp list health-checks each server; codex mcp list
#    only prints config, so Codex is probed with a real tool call instead.
check sh -c 'claude mcp list | grep -q "^atlassian:.*Connected"'
check sh -c 'codex exec --skip-git-repo-check -s read-only -o codex-mcp.txt "Call the atlassian MCP server and reply with one Jira project key I can see, and nothing else" && grep -qxE "[A-Z][A-Z0-9_]+" codex-mcp.txt'

# 5. Codex self-diagnosis, redacted, kept as evidence
codex doctor --json > "codex-doctor-$(hostname).json" 2>&1 || fail=1

exit $fail
```

The script passes the proxy to `curl` explicitly because curl, unlike the agents, never reads managed settings; without `--proxy` it would bypass the proxy where direct egress exists (a false PASS) or time out where it does not (a false FAIL). Build `CORP_CA` as `cat corp-root-ca.pem /etc/ssl/certs/ca-certificates.crt > corp-bundle.pem` (the OS bundle path varies by distribution; export the macOS keychain roots on a Mac) so hosts your inspection policy exempts still verify against their public chain.

When a line fails, the tools tell you why:

- **Claude Code:** start `claude --debug` and read `~/.claude/debug/<session-id>.txt`. `claude --debug-file ./claude-debug.txt` writes the log where you choose. A loaded CA shows as `CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS (…)`; a bad path shows a `Failed to read` line. `/status` in a session shows the active proxy and marks an unparseable proxy URL as ignored.
- **Codex:** `codex doctor` diagnoses installation, config, auth and runtime health; a bad CA file produces an error that names the variable that selected it.
- **Proxy logs:** the allowlist is proven when a week of pilot traffic shows no denied request from `claude`, `codex`, `Cursor` or `node`.

The sign-off belongs to the platform lead: the smoke test passes on every pilot machine, the denied-request count is zero for a week, and the security team has the allowlist and the managed-settings files under version control.

**Copy-paste prompt: triage a failing smoke test**

```text
Here is the output of agent-env-smoke.sh from one laptop, plus
claude-debug.txt (written by claude --debug-file ./claude-debug.txt) and
codex-doctor.json from the same machine.
For each FAIL line:
1. Name the control that failed: proxy route, TLS trust, egress allowlist, sign-in or MCP auth.
2. Quote the log line that proves it.
3. Give the fix as a change to managed-settings.json, requirements.toml or the MDM
   environment profile, never as a per-user shell edit and never by disabling TLS validation.
4. Say which other laptops will have the same problem (same OS image, same MDM group).
Stop after the diagnosis; do not change any file.
```

**Copy-paste prompt: audit MCP identities before the pilot widens**

```text
List every MCP server configured for this project and for my user in this tool.
For each server report: name, transport (stdio or http), URL or command, how it
authenticates (OAuth as me, a personal access token, a shared API key, none),
and whether it can write (create tickets, push commits, post messages).
Flag any server that authenticates with a shared or long-lived token, any stdio
server installed from a package without a pinned version, and any server that is
not in our approved list in docs/agent-policy/approved-mcp.md.
Output a table, then the three changes that most reduce risk.
```

## What breaks when you roll agents out behind a corporate proxy?

| Symptom | Cause | Recovery |
| --- | --- | --- |
| `self-signed certificate in certificate chain` in Claude Code on some laptops only | The corporate root is missing from the OS store on that image, or an old npm install on Node below 22.15 cannot read the OS store | Install the root in the OS store through MDM, or set `NODE_EXTRA_CA_CERTS` in the managed `env` block; move npm installs to the native installer |
| Codex fails TLS although Claude Code works | Codex ignores `NODE_EXTRA_CA_CERTS` | Set `CODEX_CA_CERTIFICATE` to a PEM bundle in the MDM environment |
| Background agents fail while interactive sessions work | Proxy set in a shell profile; the background supervisor started without it | Move the variables to managed settings `env`; run `claude daemon stop --any` so the next background session starts a supervisor that reads them (this ends running background sessions; add `--keep-workers` to leave detached sessions running) |
| `ERR_PROXY_TUNNEL: Proxy refused to open a tunnel: 403 Forbidden` in `claude mcp list` | The proxy denies `CONNECT` to that MCP host | Add the host to the allowlist if the server is approved; otherwise remove the server |
| An `npx` MCP server hangs at start | `registry.npmjs.org` blocked, or the server's HTTP client ignores `HTTPS_PROXY` | Allowlist the registry or point npm at your internal mirror; switch to the vendor's remote server |
| MCP OAuth login never completes | The IdP rejects the redirect URI, or the browser callback to localhost is blocked | Register an OAuth client; use `--client-id` and `--callback-port` in Claude Code, or `codex mcp login --no-browser` |
| Claude Code works, but the Chrome extension cannot connect | The organization's Claude IP allowlist sees the proxy's egress address for `bridge.claudeusercontent.com` | Route that host through the same egress as `claude.ai`, per Anthropic's network docs |
| Developers sign in to personal accounts | Login is not pinned | `forceLoginMethod` and `forceLoginOrgUUID` from a managed source; `allowed_login_methods` and `allowed_chatgpt_workspaces` in `requirements.toml` |
| Proxy asks for NTLM or Kerberos | Claude Code supports basic proxy authentication only (checked on Claude Code 2.1.283) | Put an LLM gateway that speaks your proxy's authentication in front, as covered in [model hosting](/en/org/model-hosting/) |

## Roll out in a sequence that builds evidence

1. **Week 1: five volunteers, network only.** Managed settings and `requirements.toml` deployed, proxy in log-only mode for the agent processes, smoke test on each machine. Exit when every line passes.
2. **Weeks 2–3: read-only MCP.** Documentation and issue search through Atlassian (OAuth as the user) and GitHub (a per-user PAT on the `/mcp/readonly` URL). Exit when the denied-request count is zero and the allowlist is committed.
3. **Weeks 4–6: supervised writes.** Ticket creation and pull requests, with the agent's permission mode requiring approval for writes (see [permissions and sandboxing](/en/workflows/harness/permissions-and-sandboxing/)). Exit when accepted changes and change-fail rate, as [pilot design](/en/org/pilot-design/) defines them, stay within the team's baseline band for two consecutive weeks.
4. **Then widen by team,** with the smoke test in the enrollment script so every new laptop proves itself.

Adoption spreads through people, not memos. Microsoft's study of its early-2026 rollout of Claude Code and GitHub Copilot CLI to tens of thousands of engineers found that "first use spread primarily through social networks", and that adopters "merged roughly 24% more pull requests than they would have otherwise" (Murphy-Hill, Butler and Savelieva, arXiv 2607.01418, July 2026). The authors add that "a merged PR is not the same as the value it delivers", so measure your pilot on accepted changes, not raw PR counts; the [pilot design guide](/en/org/pilot-design/) sets that up. For budget, Anthropic's own figure for Claude Code is "around $13 per developer per active day and $150-250 per developer per month" for enterprise deployments ([costs docs](https://code.claude.com/docs/en/costs), checked 2026-09-26); [cost governance](/en/org/cost-governance/) covers how to track it.

## Where to go next with corporate agent rollout

- [Enforcing one policy across every coding agent](/en/org/managed-policy/): what the managed files should allow, versioned and audited.
- [Agent identity, credentials and secrets](/en/org/agent-identity-and-secrets/): short-lived credentials for CI agents and keeping secrets out of context.
- [Where the model runs](/en/org/model-hosting/): cloud routes, gateways, residency and zero data retention.
- [Security standards and compliance](/en/org/security-compliance/) and [data privacy and enterprise policies](/en/org/privacy-data-handling/): the evidence auditors ask for.
- [Claude Code enterprise integration](/en/claude-code/team/enterprise-integration/): the full managed-settings rollout for one tool.
