Skip to main content
Codex connects to Civic through the Hub Bridge MCP server. Follow the steps below to pair the two tools in a few minutes.

​
Overview

Codex uses Model Context Protocol (MCP) to talk to external tools. Civic exposes its functionality through the @civic/hub-bridge MCP server, which you can register with Codex.

​
Prerequisites

  • Codex installed and authenticated
  • Node.js 18 or newer (required for npx @civic/hub-bridge)
  • Civic account with access to Hub Bridge

​
Quick Setup

1

Register the Civic server

Run this command to add the Civic Hub Bridge MCP server:
codex mcp add civic -- npx -y @civic/hub-bridge
This installs the bridge (if needed) and stores the connection in your Codex MCP config.
2

Launch Codex

Start the Codex session:
codex
Tip: add the --debug flag if you want to watch MCP logs while connecting.
3

Connect and sign in

Inside the Codex session, run the MCP menu command:
/mcp
Select the civic server and follow the browser sign-in flow to authorize Civic. Once the login completes, Codex confirms that the server is available for tool execution.

​
Connecting via Remote URL (HTTP)

If you prefer not to use the Hub Bridge, Codex supports connecting to Civic directly over HTTP — either via the CLI or the desktop app.

​
Option A — CLI

Step 1 — Register the remote MCP server: 
codex mcp add civic --transport http https://nexus.civic.com/hub/mcp
Step 2 — Launch Codex: 
codex
Step 3 — Run /mcp, select civic, and follow the browser sign-in flow to authorize.

​
Option B — Desktop App

You can also register the MCP server via the Codex desktop app UI:
  1. Open Settings → MCP Servers → Add Server → Streamable HTTP
  2. Paste your CIVIC_URL and CIVIC_TOKEN
  3. Save — you are ready to go.
Use Remote URL when: you cannot run local Node.js processes, prefer no local software, or connect from multiple devices. Use Hub Bridge when: you need offline capability or your environment restricts outbound HTTPS to remote MCP servers.

​
Verify the Connection

  • In Codex, run /mcp again to check that civic shows as connected
  • Test a Civic command (for example, request a tool list) to confirm the session is authorized

​
Troubleshooting

  • If the connection shows failed, re-run codex --debug to view detailed logs in your terminal
  • Ensure you have an active Civic session in your default browser; the MCP flow opens a new window for login
  • Delete and re-add the server with codex mcp remove civic followed by the setup command if you need to refresh credentials

​
Resources

Hub Bridge Guide

Full Hub Bridge configuration details

Client Compatibility

MCP support matrix for Codex

Troubleshooting

Common Codex connection fixes

Get Help

Ask setup questions in our developer Slack