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

# Diagnose

> When a customer says your MCP doesn't connect, name the failing layer — and the exact known client bug

## The doctor

```bash theme={"dark"}
mcpcomp doctor https://mcp.your-company.com/mcp
```

From a credential-less probe, `doctor` classifies which layer a reported failure lives in:

| Classification                           | Meaning                                                                         |
| ---------------------------------------- | ------------------------------------------------------------------------------- |
| NETWORK / ENDPOINT                       | The MCP endpoint itself could not be probed                                     |
| MCP SERVER CONFIGURATION                 | The server's own challenge or published metadata is the problem                 |
| IDENTITY PROVIDER / AUTHORIZATION SERVER | The authorization server's metadata, endpoints or capabilities                  |
| CLIENT AUTH STATE (inferred)             | Every layer the probe observed passes — the failure is most likely client-local |

Only requirement violations and operational outages decide the layer; advisories never do. The verdict states only what the probe observed — a layer whose check was skipped is named as unobserved, never claimed as passing — and when high-severity advisories are present, the verdict flags them, because some are known to hard-block specific clients (a `resource` mismatch in the Protected Resource Metadata blocks Claude Code outright). A fully green server plus a failing client is itself the diagnosis — the commonest support case, where the server operator's dashboards are green and the customer's client is holding stale auth state.

## Name the client, get the known bugs

```bash theme={"dark"}
mcpcomp doctor https://mcp.your-company.com/mcp --client codex
```

With the failing client named (`claude-code`, `codex`, `cursor` or `vscode`), a CLIENT AUTH STATE verdict expands into that client's documented failure patterns — condition, symptom, and the action that clears it:

```text theme={"dark"}
Known codex auth-state failure patterns:
  - shared brokered token state went stale across devices
      symptom: every tool call fails with -32603 "http/request failed" while the server is healthy
      action:  run `codex mcp login <server>` again on the failing machine
```

Each pattern is distilled from reading the client's source, changelog, or staff-confirmed reports — not speculation. The support flow this enables: tell the stuck customer to run one command, and the report that comes back answers whose layer it is and, when it is the client, which known bug.

## End-to-end verification

```bash theme={"dark"}
export MCPCOMP_CLIENT_ID=... MCPCOMP_CLIENT_SECRET=...
mcpcomp verify https://mcp.your-company.com/mcp
```

`verify` makes a synthetic machine-to-machine connection through the MCP OAuth client-credentials extension: token issuance, then an authenticated `tools/list`. On failure it says which side of the token endpoint the fault is on — no token issued (credentials or authorization server) versus token issued but the call failed (the server's own validation).

<Warning>
  `verify` presents credentials, so it never runs without a client id and secret you provisioned — set `MCPCOMP_CLIENT_ID` and `MCPCOMP_CLIENT_SECRET` in the environment. There are deliberately no flags for them.
</Warning>

## Use it from an agent

```bash theme={"dark"}
mcpcomp serve
```

The scanner is an MCP server itself: `serve` (stdio) exposes `scan_auth` and `diagnose_auth_failure` as read-only tools. Add it to any MCP client and an agent whose MCP connection is failing can diagnose it without leaving the conversation — `diagnose_auth_failure` accepts the same optional `client` input as `--client`.