Skip to main content
Version: 3.0

Codex

Give Codex access to MaestroHub through its MCP server, using a Personal Access Token and your workspace ID.

Config file
~/.codex/config.toml
Format
TOML
Endpoint
/api/v1/mcp

Codex supports MCP servers via a TOML configuration file.

Configuration​

Add the following to your Codex configuration file:

  • macOS / Linux: ~/.codex/config.toml
  • Windows: %USERPROFILE%\.codex\config.toml
[mcp_servers.maestrohub]
url = "https://<your-instance>/api/v1/mcp"
http_headers = { "Authorization" = "ApiKey <your-token>", "X-Workspace-ID" = "<your-workspace-id>" }

Or add it from the command line. codex mcp add has no option for custom headers, so it sends the token as a bearer token read from an environment variable:

export MAESTROHUB_TOKEN=<your-token>
codex mcp add maestrohub --url https://<your-instance>/api/v1/mcp --bearer-token-env-var MAESTROHUB_TOKEN

Then add the workspace header to the entry it wrote in config.toml:

[mcp_servers.maestrohub]
url = "https://<your-instance>/api/v1/mcp"
bearer_token_env_var = "MAESTROHUB_TOKEN"
http_headers = { "X-Workspace-ID" = "<your-workspace-id>" }

Replace the placeholders:

  • <your-instance>: your MaestroHub domain (e.g., maestro.example.com)
  • <your-token>: the Personal Access Token you created
  • <your-workspace-id>: your workspace ID (found in the URL or workspace settings)
note

For local deployments without TLS, change https:// to http:// in the URL (e.g., http://localhost:6163/api/v1/mcp).

Tips​

  • Codex uses TOML format instead of JSON.
  • The config file is global, so MaestroHub will be available in all projects.
  • Create the directory if it doesn't exist:
    • macOS / Linux: mkdir -p ~/.codex
    • Windows: mkdir %USERPROFILE%\.codex