Get access

Agent clients · 24 / 42

Codex

Connect Codex to the hosted Northsun MCP endpoint, verify the authenticated tools, and remove the connection and handle an exposed key safely.

Codex can use Northsun through its shared MCP configuration. Register the hosted Streamable HTTP endpoint, source the bearer token from NORTHSUN_API_KEY, then verify the server and run a read-only tool call. This gives Codex access to Northsun tools; it does not make OpenAI a Northsun partner or turn every MCP tool into a stable public API.

Prerequisites

  • Codex CLI installed and able to read its normal configuration.
  • A Northsun API key stored in the environment as NORTHSUN_API_KEY.
  • A test caller that already exists in your Northsun tenant for read-only verification.
export NORTHSUN_API_KEY="..."

Do not paste the key into a prompt, repository file, screenshot, or support message. See Authentication for the tenant and key boundary.

Add Northsun

Codex supports Streamable HTTP MCP servers and an environment-backed bearer-token option:

codex mcp add northsun \
  --url https://mcp.northsun.ai/mcp \
  --bearer-token-env-var NORTHSUN_API_KEY

The equivalent config.toml entry is:

[mcp_servers.northsun]
url = "https://mcp.northsun.ai/mcp"
bearer_token_env_var = "NORTHSUN_API_KEY"

Codex CLI and the Codex IDE extension share MCP configuration. Start a new session after changing the file so the host performs a fresh handshake.

Verify the connection

First confirm that Codex knows about the server:

codex mcp list

Then, in a new Codex session:

  1. Inspect the available Northsun tools.
  2. Call caller_lookup with a plain E.164 test number already in your tenant (for example +15551234567); the server percent-encodes it for you.
  3. Treat 404 as a valid empty state and 401 as an authentication failure.
  4. Confirm that a broader workflow uses only the tool schema shown in the current session.

A configured server is not yet a verified connection. The read-only call proves that the bearer token reached Northsun and established the expected tenant.

Common failures

SymptomLikely causeFix
Server appears but initialization failsCodex was launched without NORTHSUN_API_KEY in its environmentExport the variable where the Codex process starts, then open a new session.
401 unauthorizedMissing, revoked, or incorrect Northsun keyVerify the environment variable name; if exposure is possible, ask us to revoke it through the contact page, naming the last six characters of the key.
Northsun tools do not appearStale session or disabled serverRun codex mcp list, confirm the entry is enabled, and start a fresh session.
A tool name or input differs from this guideMCP contract changedInspect the current tool list and schema; do not guess fields from an older screenshot.
caller_lookup returns 404The key is valid, but the test caller is absent in that tenantUse an existing controlled test caller or complete the Quickstart.

Remove the connection or replace the key

Remove the local server definition with:

codex mcp remove northsun

If the key may have appeared in a file, terminal capture, or log, removing the config is not enough. Ask us to revoke it through the contact page, naming the last six characters of the key, then replace NORTHSUN_API_KEY with the key you are issued and restart Codex before reconnecting.

Stable and beta boundaries

The frozen public REST contract remains the three endpoints in the API reference. MCP exposes the stable caller-memory tools plus broader contact and governed-context tools whose schemas can evolve independently. Inspect the live tool list when upgrading. Beacon and proactive context delivery are not implied by this connection.

This is a Northsun interoperability guide based on Codex's documented MCP configuration. It is not an OpenAI endorsement, certified integration, or support commitment.

Related links