> For the complete documentation index, see [llms.txt](https://learning.contextqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learning.contextqa.com/mcp-server/troubleshooting.md).

# MCP Connection Troubleshooting

Diagnose ContextQA MCP health, URL, transport, OAuth callback, workspace access, tool discovery, permissions, and failed calls without exposing secrets.

## Quick answer

Diagnose a ContextQA MCP problem in layers: confirm the hosted service is healthy, verify the exact HTTP URL, inspect Claude Code’s server status, complete the OAuth callback, run one harmless read-only request, then separate wrong-workspace or permission problems from a genuinely unavailable tool. Stop after the first failing layer and capture a sanitized evidence record; repeatedly removing, re-adding, or reauthorizing the server can hide the original cause.

## The connection path

```mermaid
flowchart LR
    A[Claude Code config] --> B[Hosted MCP health]
    B --> C[OAuth authorization]
    C --> D[ContextQA account/workspace]
    D --> E[Connected tool manifest]
    E --> F[Individual tool call]
```

A failed tool call does not necessarily mean the server failed to connect. A healthy connection can still encounter an unavailable capability, rejected permission, invalid resource ID, or execution error.

{% hint style="info" %}
The current hosted endpoint and setup authority is [mcp.contextqa.com/docs](https://mcp.contextqa.com/docs). Claude Code client behavior is defined by [Anthropic’s MCP documentation](https://code.claude.com/docs/en/mcp). Recheck both after a client or server update.
{% endhint %}

## Before you change anything

Record:

```
Observed time and timezone:
Claude Code version:
Operating system:
Project directory:
Server name in Claude Code:
Configured server URL (no headers/tokens):
Server status shown by Claude Code:
ContextQA account identity:
Expected workspace:
Exact safe prompt or tool action:
Error text with secrets removed:
Last time the connection worked:
Recent client/config/account changes:
```

Do not include access tokens, cookies, authorization headers, passwords, test-user credentials, or private test data.

## Step 1: Check hosted service health

Open the documented health endpoint in a browser or use a read-only request:

```bash
curl --fail --silent --show-error https://mcp.contextqa.com/health
```

Use the response documented by the current [ContextQA MCP troubleshooting reference](https://mcp.contextqa.com/docs/faq). If the health request fails:

* confirm DNS and outbound HTTPS access;
* check corporate proxy/TLS interception behavior;
* retry from an approved alternate network only if policy permits; and
* record the timestamp and sanitized network error before escalating.

Do not troubleshoot workspace permissions while the service is unreachable.

## Step 2: Verify the connection definition

The current hosted server uses:

```
URL: https://mcp.contextqa.com/mcp
Transport: HTTP
Authentication: OAuth 2.0 through the browser
```

For Claude Code, the documented add command is:

```bash
claude mcp add --transport http contextqa https://mcp.contextqa.com/mcp
```

Inspect the existing entry before adding a duplicate:

```bash
claude mcp list
claude mcp get contextqa
```

Check for:

* a missing `/mcp` path;
* `http://` instead of `https://`;
* an older SSE or local-process configuration;
* a different server named `contextqa` in another scope;
* a project configuration that has not been approved/trusted; and
* environment/header customization that is not part of the supported setup.

Claude Code supports local, project, and user MCP scopes with precedence rules. If the displayed definition differs from the one you edited, inspect the active scope using Anthropic’s current MCP documentation.

## Step 3: Inspect Claude Code server status

Inside Claude Code, open:

```
/mcp
```

Classify the status:

| Status               | Meaning to investigate                                                 | Next action                                                       |
| -------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Connected            | Transport is available; continue to harmless request and tool manifest | Step 5                                                            |
| Needs authentication | OAuth has not completed or must be renewed                             | Step 4                                                            |
| Pending/connecting   | Client is still establishing the connection                            | Wait within the client’s documented boundary; then capture status |
| Failed               | Config, transport, discovery, or server connection failed              | Read the client error and return to Steps 1–2                     |
| Server absent        | Active configuration did not load                                      | Check scope, syntax, project trust, and client restart            |

Do not infer tool availability from connection status alone.

## Step 4: Complete OAuth without interrupting the callback

Trigger authentication from the MCP client; do not open an old login URL directly.

1. Reconnect the `contextqa` server or issue the harmless read-only prompt in Step 5.
2. Sign in using the intended ContextQA account.
3. Review the authorization screen.
4. Complete authorization.
5. Keep the browser page open until the callback and redirect finish.
6. Return to `/mcp` and confirm the server is connected.

If the callback fails:

| Symptom                                             | Check                                                                                                 |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Login page says the session is invalid/expired      | Restart authorization from Claude Code; do not reuse the old URL                                      |
| Browser signs in but client remains unauthenticated | Confirm callback completed; inspect browser blocking, proxy, or localhost callback policy             |
| Wrong account/workspace appears                     | Sign out or disconnect, then restart with the intended account                                        |
| Authorization repeatedly opens                      | Check system clock, browser policy, client credential storage, and whether the grant is being revoked |

Do not document a fixed token lifetime as an operational guarantee. Use the current hosted reference and the client’s observed behavior.

## Step 5: Run one harmless read-only check

Ask:

```
Using the connected ContextQA MCP server, list my test cases without creating,
editing, deleting, or running anything. State which workspace/account context
you can see and report any missing permission without retrying a write action.
```

Interpret the result:

| Result                      | Likely layer                                                   |
| --------------------------- | -------------------------------------------------------------- |
| Tests are returned          | Connection, authentication, and basic workspace read succeeded |
| Empty list with no error    | Correct connection; possibly wrong workspace or no tests       |
| Unauthorized/reauthorize    | OAuth/account layer                                            |
| Forbidden/permission denied | ContextQA role or tool authorization layer                     |
| Tool not found              | Connected manifest/capability layer                            |
| Network/discovery error     | Transport/server layer                                         |
| Invalid resource/argument   | Individual call or prompt layer                                |

Verify an empty result in the ContextQA portal before reporting it as a connection failure.

## Step 6: Verify the connected tool manifest

The client’s connected manifest is authoritative for the exact tools and schemas available in that session. Do not design a workflow from a historical tool count or a copied blog table.

Create a capability record:

| Workflow action           | Tool visible now? | Required inputs understood? | Permission test                            | Decision                      |
| ------------------------- | ----------------- | --------------------------- | ------------------------------------------ | ----------------------------- |
| List existing tests       |                   |                             | Harmless read                              | Supported / Missing / Blocked |
| Read test steps           |                   |                             | Harmless read                              |                               |
| Create a test             |                   |                             | Do not test in production without approval |                               |
| Run a saved case/plan     |                   |                             | Staging/disposable only                    |                               |
| Retrieve results/evidence |                   |                             | Existing run                               |                               |
| Edit/delete/apply healing |                   |                             | Separate authorization                     |                               |

If the server is connected but a tool is absent, classify it as `Missing in connected manifest`, not `Connection failed`.

## Step 7: Separate permission from capability

| Observation                                         | Classification                                       |
| --------------------------------------------------- | ---------------------------------------------------- |
| Tool is absent from manifest                        | Unavailable in this connected version/account/client |
| Tool is present but client asks for approval        | Client permission boundary                           |
| Client permits call but ContextQA returns forbidden | ContextQA account/workspace role boundary            |
| Tool accepts request but rejects its resource ID    | Input/resource boundary                              |
| Tool starts an execution that later fails           | Execution/application boundary                       |

Do not broaden client or workspace permissions until the required action and owner are clear. A read-only workflow does not need test-delete or release-change authority.

## Step 8: Diagnose wrong-workspace results

If the connection works but expected tests are missing:

1. Record the signed-in ContextQA account.
2. Confirm the expected organization/workspace in the portal.
3. List tests without filters.
4. Search for one known non-sensitive test name or ID.
5. Confirm that account has permission to that workspace.
6. Disconnect and reauthorize only if the wrong account is active.

Do not paste workspace-private test names into public support channels.

## Step 9: Diagnose an individual failed call

Capture:

```
Client/server versions:
Manifest timestamp:
Tool/action requested:
Safe parameter names (redact values):
Workspace/account identity:
Resource ID or sanitized substitute:
Response category and request/run reference:
Whether a harmless read still succeeds:
Reproduction frequency:
```

If a harmless read succeeds, keep the incident scoped to the individual capability. Do not remove a working server configuration.

## Recovery decision tree

```mermaid
flowchart TD
    A[Problem observed] --> B{Health endpoint reachable?}
    B -- No --> C[Network/service escalation]
    B -- Yes --> D{Server loaded in /mcp?}
    D -- No --> E[Fix URL, transport, scope, syntax, or trust]
    D -- Yes --> F{OAuth complete?}
    F -- No --> G[Restart client-led OAuth and finish callback]
    F -- Yes --> H{Harmless read succeeds?}
    H -- No --> I[Check account, workspace, and permission]
    H -- Yes --> J{Required tool in manifest?}
    J -- No --> K[Mark capability unavailable; redesign or escalate]
    J -- Yes --> L[Diagnose call inputs, resource, or execution]
```

## Sanitized support packet

Send only:

* issue start time and timezone;
* client and OS versions;
* server name, URL, transport, and configuration scope without secrets;
* health-check outcome;
* `/mcp` status;
* intended account/workspace identifiers that are safe to share;
* harmless read result;
* tool/action name and sanitized error;
* request or run reference when available; and
* exact reproduction steps and recent changes.

Before sending, search the packet for `Authorization`, `Bearer`, `token`, `cookie`, `password`, session IDs, test-user credentials, private URLs, and sensitive test data.

## Common questions

<details>

<summary>Should I remove and re-add the server first?</summary>

No. Record the active definition and failure layer first. Re-adding can change scope or account state and make the original problem harder to reproduce.

</details>

<details>

<summary>Why does the hosted reference show a different number of tools?</summary>

Server versions and account capabilities can change. Use the connected manifest for exact names, schemas, and availability; use documentation counts only as dated historical context.

</details>

<details>

<summary>Does an empty test list mean OAuth failed?</summary>

Not necessarily. If the call completes without an authorization error, check the signed-in account, workspace, filters, and whether tests exist.

</details>

## Related documentation

* [Install and set up the MCP server](/mcp-server/installation-and-setup.md)
* [Authentication](/mcp-server/authentication.md)
* [Agent integration guide](/mcp-server/agent-integration-guide.md)
* [MCP tool reference](/mcp-server/tool-reference.md)
* [Execution recovery](/execution/running-tests.md#recover-a-queued-timed-out-or-missing-result)

{% hint style="info" %}
**Connection works, but your required workflow is still blocked?** [**Book a technical MCP review →**](https://contextqa.com/book-a-demo/?utm_source=learning.contextqa.com\&utm_medium=referral\&utm_campaign=docs_demand_gen\&utm_content=mcp_troubleshooting) — Bring the sanitized support packet and the intended workflow boundary.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://learning.contextqa.com/mcp-server/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.