# 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:

```bash
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?](https://dev.nominal.io/quickstart/mcp.md#your-api-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](https://dev.nominal.io/quickstart/mcp.md#nominal-managed).

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](https://dev.nominal.io/quickstart/mcp/quickstart-self-hosted.md#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](https://dev.nominal.io/quickstart/mcp.md#connect).

## Codex

“invalid_scope”

Include the scope when signing in:

```bash
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](https://dev.nominal.io/quickstart/mcp.md#connect).

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](https://dev.nominal.io/quickstart/mcp/quickstart-self-hosted.md#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](https://dev.nominal.io/quickstart/quick/quick-sql.md).

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.