> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuro-tech.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot MCP

> Fix common Codex, OAuth, endpoint, and permission failures

## `404 Not Found`

Use one of the exact built-in paths:

```text theme={null}
/MCP/Files
/MCP/EventLog
/MCP/Content
/MCP/XMPP
```

There is no combined `/MCP` endpoint. Also check URL casing, reverse-proxy path rewriting, and whether the module providing the endpoint started successfully.

## `codex mcp login` cannot discover OAuth

Open both metadata documents directly:

```bash theme={null}
curl --fail https://neuron.example.com/.well-known/oauth-authorization-server
curl --fail https://neuron.example.com/.well-known/oauth-protected-resource
```

If either fails, fix the Neuron, TLS certificate, DNS, or proxy before changing Codex configuration.

## Client registration fails

Dynamic registration is optional. Ask the operator whether DCR is enabled and tested. Otherwise remove the MCP entry and add it again with a supplied client ID:

```bash theme={null}
codex mcp remove neuron-files
codex mcp add neuron-files --url https://neuron.example.com/MCP/Files --oauth-client-id YOUR_CLIENT_ID
```

## Login succeeds but requests return `403`

The account lacks one or more requested privileges. Compare each requested scope with its role privilege:

```text theme={null}
MCP:Files:Resources:Read
OAUTH.Scope.MCP.Files.Resources.Read
```

After the role changes, log in again so Codex obtains a token with the new scope.

## No tools or resources appear

* Confirm Codex is connected to the intended specialized endpoint.
* Run `codex mcp list` and inspect `/mcp` inside Codex.
* Check that the requested leaf scopes include the operation you expect.
* Check Neuron startup and event logs for module errors.

## Bearer token works only in one terminal

`--bearer-token-env-var` stores the environment variable's **name**, not its value. Define that variable in every process that launches Codex. Do not put the token itself in `config.toml`.

## Information to collect

Record the endpoint, UTC time, client ID, requested scopes, HTTP status, JSON-RPC error, Neuron version, and event ID. Remove access tokens, refresh tokens, authorization codes, cookies, client secrets, and passwords.