Skip to main content

Use Codex with Spectral MCP

Connect Codex to Spectral through the Spectral MCP server to create structural models while you work in a codebase. Codex CLI, the IDE extension, and the Codex app share MCP configuration, so you only need to configure the Spectral server once.

Requirements​

  • Codex CLI installed and authenticated.
  • A Spectral account that can sign in through https://auth.spectralco.co.
  • Network access to https://mcp.spectralco.co/mcp.
  • Permission to grant these Spectral MCP scopes:
    • mcp:models:read
    • mcp:models:write
  • Access to one of these Codex config locations:
    • ~/.codex/config.toml for your user config.
    • .codex/config.toml inside a trusted project for project-scoped config.

Codex loads project .codex/config.toml files only for trusted projects. If a project is not trusted, Codex ignores project MCP settings and uses your user config instead.

Setup​

Step 1: Add the Spectral OAuth config​

Add this table to ~/.codex/config.toml, or to .codex/config.toml in a trusted project:

[mcp_servers.spectral]
url = "https://mcp.spectralco.co/mcp"
oauth_resource = "https://mcp.spectralco.co/mcp"
scopes = ["mcp:models:read", "mcp:models:write"]
default_tools_approval_mode = "prompt"

default_tools_approval_mode = "prompt" keeps Spectral tool calls reviewable. That is important for write tools that create models or add model elements.

Step 2: Log in with OAuth​

Run:

codex mcp login spectral

Codex opens the Spectral OAuth flow in your browser. Sign in, review the requested scopes, and approve the connection.

If you want to request the scopes explicitly from the CLI, run:

codex mcp login spectral --scopes mcp:models:read,mcp:models:write

Step 3: Confirm the server is available​

Run:

codex mcp list

Then start Codex from the CLI, IDE extension, or Codex app. In the CLI terminal UI, use:

/mcp

Confirm the spectral server is enabled and its tools are listed.

Step 4: Test model creation​

Use a small test prompt:

Use Spectral to create an empty model named Codex MCP Smoke Test.

Review the proposed tool call before approving it.

What Codex Can Access​

With the approved scopes, Codex can ask Spectral to:

  • Create a new model owned by your Spectral account.
  • Add structural elements to a model you can write to.
  • Return a viewer payload or viewer URL for the created model.

Example Workflows​

WorkflowPrompt
Create test dataCreate a small Spectral test model named "Codex Frame Trial". Ask before running write tools.
Add elementsAdd four columns and two beams to the test model using Spectral, then give me the viewer URL.
Pair with code workGenerate a script that prepares a model-creation JSON payload, then use Spectral to create the model.

Privacy And Data Handling​

  • Codex receives only the Spectral data returned by the MCP tools you ask it to use.
  • OAuth credentials are stored by Codex using its local credential storage for your user account.
  • If you use project .codex/config.toml, review it before committing. Shared config can include the server URL and scopes, but it must not include private credentials.
  • Model names, element payloads, viewer payloads, and prompts may become part of the Codex conversation where you use the server.

Disconnect Or Remove Spectral​

To remove the OAuth grant from Codex, run:

codex mcp logout spectral

To stop loading the server, either remove the [mcp_servers.spectral] table or disable it:

[mcp_servers.spectral]
enabled = false

Troubleshooting​

codex mcp login spectral cannot find the server​

Confirm the config table is named [mcp_servers.spectral] and that Codex is reading the config file you edited. For project config, confirm the project is trusted.

OAuth opens but fails after sign-in​

Confirm the config uses:

oauth_resource = "https://mcp.spectralco.co/mcp"

Also confirm the requested scopes are mcp:models:read and mcp:models:write.

The callback does not complete​

Retry the login from a local terminal. If your environment requires a fixed OAuth callback URL or port, configure Codex MCP OAuth callback settings in config.toml according to your Codex environment policy.

Tools are missing in the IDE or app​

Codex CLI, IDE, and app share MCP config. Restart the IDE extension or app after editing config.toml, then open MCP settings or run /mcp in the CLI to confirm the server is loaded.

Write tools ask for approval​

That is expected. default_tools_approval_mode = "prompt" keeps Spectral write actions reviewable before Codex creates models or adds elements.

Access expires​

Run:

codex mcp login spectral

Then retry the prompt.

GET /mcp returns 405​

That is expected for the current Streamable HTTP deployment. The MCP endpoint accepts protocol requests over POST /mcp.

Help And Next Steps​

  • For shared MCP concepts, see /docs/mcp/overview.
  • For Spectral authentication details, see /docs/mcp/authentication.
  • For host-level MCP troubleshooting, see /docs/mcp/troubleshooting.
  • For Codex MCP configuration details, see the OpenAI Codex MCP documentation: https://developers.openai.com/codex/mcp.
  • If setup still fails, contact Spectral support with your Codex surface (CLI, IDE, or app), the config location you used, the approximate login time, and the failing command or prompt.