Troubleshooting

Find the symptom below. After changing connection settings, reconnect your client and try again.

Connection and sign-in

“Does not support dynamic client registration”

The client ID is missing. In Claude Code, add the server with both OAuth flags:

claude mcp remove nominal
claude mcp add nominal \
  --transport http \
  https://api.gov.nominal.io/mcp \
  --client-id nominal-mcp \
  --callback-port 54545

If your organization uses a different host, replace it as described in Using a different Nominal host?. In Codex, use client_id under [mcp_servers.nominal.oauth]. A flat oauth_client_id setting is ignored.

The redirect URI is not registered

In Claude Code, check that you included --callback-port 54545. Without it, the client chooses a random port. Add the server again using the full command in Nominal-managed setup.

For a self-hosted deployment, ask your administrator to register the exact callback host, port, and path, for both localhost and 127.0.0.1. Codex adds an extra path segment. Wildcard entries are not supported. See self-hosted OAuth.

For Nominal-managed deployments, contact your Nominal representative if the complete command still fails. You do not register callbacks yourself.

Callback port 54545 is already in use

Another process is using the port. Close that process and try again.

To use another port, self-hosted administrators must register the matching callback. For a Nominal-managed deployment, contact your Nominal representative.

A PKCE error or “invalid_target”

Your client must support PKCE (S256). For invalid_target, token-exchange parameters must be sent in the form-encoded request body. See other clients.

Codex

“invalid_scope”

Include the scope when signing in:

codex mcp login nominal --scopes mcp:tools

A TOML type error or “400 Bad Request” during sign-in

Move mcp_oauth_callback_port = 54545 and mcp_oauth_callback_url above every [table] header in ~/.codex/config.toml. The port must be an unquoted integer. Compare with the complete Codex configuration.

My configuration has no effect

Check that you edited the user configuration, ~/.codex/config.toml, then run codex mcp list and confirm that nominal is listed.

Self-hosted

Sign-in works, but the MCP endpoint returns 401

If your administrator recently enabled OAuth, your client may still be sending an API key. Reconfigure your client for OAuth. A deployment accepts OAuth or API keys, never both.

Sign-in works, then I see “500” or “server_error”

Ask your administrator to confirm that the MCP issuer is one of the deployment’s trusted OIDC providers.

“reauthorization_required” after sign-in

The identity provider did not return a refresh token. Ask your administrator to enable the refresh token grant on the Okta application. Enabling only the offline_access scope is not enough.

Workbook questions

The agent can’t read raw samples

Use the agent to arrange plots, variables, and comparisons, then inspect the values in Nominal. To query data points, use SQL.

A channel or change is missing

Confirm that the workbook uses the intended run or asset as a data input. Ask the agent to list the workbook’s tabs and available channels. Check that you opened the tab it edited and that the visible time range covers the test.

Still stuck?

Contact your Nominal representative with your client and version, the exact error, and your API host. For self-hosted deployments, include whether https://<api-host>/.well-known/oauth-authorization-server returns 200.

Never include tokens, authorization codes, or client secrets. A loopback redirect_uri is safe to share.