Troubleshoot the MCP server

For hosted ChatGPT, first verify the owning region, OAuth connection and selected workspace with ChatGPT setup. No local CLI is required. An HTTP 401 with protected-resource metadata before sign-in is the expected OAuth challenge for an MCP POST; it is not proof that the server is broken. Opening /mcp directly in a browser sends GET and can return 405 Method Not Allowed. Use the MCP host connection flow; that endpoint is not an HTML sign-in page.

For local stdio, start with the terminal used by the same operating-system account as the MCP host:

node --version
teamgrid --version
npm list --global @teamgrid/mcp-server --depth=0
teamgrid --profile default auth status --check

Then start teamgrid-mcp --profile default --tool-profile core directly. A healthy JSON-RPC stdio server normally waits silently for host input. Stop it with Ctrl+C after this check; do not type prompts into its standard input.

Browser login is enabled in Production DE and US. Use auth login --manual as an alternative for initial setup, or auth login --manual --replace when replacing an existing local profile. See browser-login availability.

Diagnosis matrix

Tool errors versus startup errors

authentication_required, credential_expired, profile_credential_mismatch, and invalid command arguments prevent the stdio server from starting. They are printed before the process waits for MCP input.

After the server is connected, TeamGrid request failures use a stable MCP error envelope:

{
  "error": {
    "code": "insufficient_scope",
    "detail": "<redacted TeamGrid request error>",
    "status": 403
  }
}

API and SDK errors preserve their valid machine-readable code. When available, the envelope also contains status, a safe requestId, and valid retryAfterMs without shortening the server delay. Unknown failures use teamgrid_request_failed; malformed upstream codes fall back to teamgrid_api_error or teamgrid_client_error. MCP also sets isError: true.

Oversized results use result_too_large. Schema validation errors are produced by the MCP protocol layer before the TeamGrid handler runs, so their display varies by host.

Information safe to share with support

Share the MCP server version, CLI version, Node.js version, operating system, selected profile name, selected tool profile, tool name, non-secret arguments, timestamp, and redacted error detail. The API response metadata may contain a request ID that is safe and useful for tracing.

Never share an API token, browser authorization code, PKCE verifier, webhook signing secret, Authorization header, credential-store contents, or an unreviewed tool transcript. If accidental exposure is possible, revoke or rotate the affected credential before continuing diagnostics.

Write and OAuth failures

The table below covers consent and outcome recovery.

Early ChatGPT reconnect prompts

The initial hosted grant contains workspace:read; that permission does not authorize task, project or member reads, or any write. A visible tool catalog is not a list of permissions already granted to your connection. See who chooses the permissions.

TeamGrid access tokens currently last up to five minutes. ChatGPT should renew them while the underlying OAuth grant remains active. A successful renewal retains the token’s scopes; it cannot turn a workspace-only grant into a task write grant. Repeated refresh attempts therefore cannot resolve missing consent.

If a reconnect prompt appears before a new operation:

1. Check the selected workspace and the permissions approved for that connection in Settings → Team → Developer Center → Access.
2. Compare those scopes with the requested tool’s reference. Review any new TeamGrid consent screen; do not grant unrelated permissions to diagnose the issue.
3. If ChatGPT keeps requesting reconnection without showing the needed scopes, report the operation, approximate time and region to TeamGrid support. Support can distinguish an active grant with insufficient scopes from an expired or revoked grant using token lifecycle and HTTP challenge evidence.

An HTTP401 invalid_token, an HTTP403 insufficient_scope, a business permission denial and an HTTP503 provider outage require different remedies. Cookie deletion or extending token lifetimes does not correct a missing OAuth permission. Never send access or refresh tokens, authorization codes, cookies or Passkey assertions to support. No business write is needed to diagnose this boundary.

Confirmation closes before a passkey prompt

A briefly opening confirmation window does not establish that the browser cannot use passkeys. When TeamGrid reports an invalid sign-in session, the confirmation stopped before the passkey transport was issued. A workspace handoff can retain an older central sign-in session whose security state is no longer valid.

1. Use Sign out and sign in again when the consent screen offers it. Otherwise, sign out on TeamGrid’s normal central sign-in page.
2. Sign in normally with the intended account. Confirm that this account belongs to the required workspace; the workspace picker shows only workspaces it can access.
3. Start a new connection request from the MCP host and review its workspace and scopes again.
4. Complete the normal passkey confirmation if requested.

The session-specific recovery message is included in the deployed Production App release. Other permission, workspace or routing errors can produce the generic connection-failure message; do not treat that message alone as proof of a session failure. An expired request must be restarted in the host. Refreshing an old consent URL or switching browsers does not renew it. Keep session validation and passkey confirmation enabled throughout recovery.

A separate Staging failure on 1 October 2026 occurred after the server successfully issued the confirmation transport. A small difference between server and browser clocks caused the App to reject that valid response before displaying the passkey page. Signing in again or switching browsers does not correct this App defect. The correction keeps server expiry authoritative and bounds the browser’s wait independently of its wall clock; it is included in the deployed Production App release.

Support can distinguish these failures using the preparation result without collecting cookies, transport tokens, authorization codes or passkey assertions.

A workspace-routing failure can also stop the confirmation before a passkey prompt. When a proxy loses the original workspace host on the realtime connection, TeamGrid cannot validate that connection against the signed-in workspace. Support must check the actual App release and host routing; the correction must retain workspace isolation and session validation. Do not disable passkey confirmation, change the selected workspace or grant broader scopes to work around it.

Passkeys and workspaces in different regions

A Passkey belongs to your TeamGrid account, not to each workspace. A US-hosted workspace can therefore request confirmation on TeamGrid’s central sign-in page at login.teamgrid.app. You do not need to register another Passkey in that workspace. The confirmation still belongs to the selected workspace and the exact permissions shown in the original request.

The message “This request is unavailable for this account. Return to the original window.” means that the confirmation cannot be matched to the current account, session and request. An expired request, a different signed-in account or a regional session-routing problem can reach this boundary before a Passkey is requested. The message alone cannot identify which condition caused it.

1. Return to the original connection window. If TeamGrid offers a new sign-in, use the intended account and its normal central sign-in method.
2. If the request expired, restart the connection in ChatGPT or your MCP host. Refreshing or reopening the old popup cannot renew it.
3. Check the selected workspace and permissions, then confirm the new request.
4. If a fresh request still fails, share the time, selected region and workspace with support. Support must verify the regional transport and session binding; copying Passkeys between workspaces or repeatedly clearing cookies cannot correct a server-routing defect.

Do not send the consent URL, browser session, authorization code or Passkey assertion to support. Keep account confirmation and workspace permissions enabled.