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

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.

The current hosted endpoint and setup authority is mcp.contextqa.com/docs. Claude Code client behavior is defined by Anthropic’s MCP documentation. Recheck both after a client or server update.

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:

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

Use the response documented by the current ContextQA MCP troubleshooting reference. 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:

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

Inspect the existing entry before adding a duplicate:

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

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

Should I remove and re-add the server first?

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.

Why does the hosted reference show a different number of tools?

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.

Does an empty test list mean OAuth failed?

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

Related documentation

• Install and set up the MCP server
• Authentication
• Agent integration guide
• MCP tool reference
• Execution recovery

Connection works, but your required workflow is still blocked? Book a technical MCP review → — Bring the sanitized support packet and the intended workflow boundary.