Verify And Troubleshoot GroundX Agent Harness

Use this page after installing GroundX Agent Harness (see Install GroundX Agent Harness) or connecting hosted MCP (see Connect Hosted MCP Tools) to confirm the install worked and to work through the most common failures. Every step below collects evidence without asking for a raw API key in chat.

Verify The Plugin

If you only connected hosted MCP (for example through a connector-only client, per Install GroundX Agent Harness — Claude Desktop Connector-Only Builds) and never installed the plugin/skill bundle, skip this section — there are no skills to verify. Go to Verify Hosted MCP instead.

Run these checks without pasting secrets into chat. They’re the same prompts from Install GroundX Agent Harness:

List the GroundX Agent Harness skills you have available.

Use the GroundX Agent Harness references to explain the safest document ingest -> status polling -> search flow. Do not ask me for an API key.

Show my GroundX account context using the connector. Do not include raw credentials.

If you have a local checkout of the repository, you can also run the local helper:

1
node scripts/doctor.mjs

If a skill or the plugin itself doesn’t show up, the client is likely still running with the pre-install session state. Restart or reload before troubleshooting further:

• Claude Code CLI / VS Code + Claude / Claude Code Desktop — run /reload-plugins, or start a new session.
• Claude Desktop (connector-only builds) — enable the connector in the current conversation; a new conversation picks it up automatically.
• Codex CLI / Codex Desktop — start a new Codex session after installing.

If the skills list is still empty after a reload/restart, revisit the install steps for your client in Install GroundX Agent Harness before continuing.

Verify Hosted MCP

If GroundX MCP tools are visible at all, confirm you’re looking at the right account context before doing anything else:

Show my GroundX account context using the connector. Do not include raw credentials.

This calls the always-present groundx_account_context tool (see Connect Hosted MCP Tools), which takes no input and returns the resolved account type, mode, granted scopes, base URL, and enabled tool groups for the current session, with no secrets in the response.

With a regular user key, confirm normal GroundX tools are available and partner/admin tools are not visible.

A regular user key should show the ordinary default-tool surface (ingest, search, bucket/group management, health — scoped per Scope And Visibility) and should not show partner- or admin-only tools. If a regular user key does show partner/admin tools, that’s a bug to report, not expected behavior. Collect the account context output and the visible tool list (see Evidence To Collect) and escalate it rather than treating it as a working state.

401 Or Reauthentication Required

Symptoms: the MCP client fails to connect, or a tool call returns a 401 / “unauthorized” error.

A quick REST sanity check confirms whether the key is the problem, independent of the MCP layer:

1
curl -H "X-API-Key: YOUR_API_KEY" https://api.groundx.ai/api/v1/health/api

A 200 response means the key is accepted. A 401 means the key needs attention (revoked, wrong environment, or never valid) — fix that before debugging MCP further. Never paste the real key into this command in chat; run it yourself in a terminal with the key already in your environment.

Missing Tools

A tool you expect isn’t showing up in the client’s tool list. Work through these in order:

1. Scope mismatch. Tool visibility follows the derived-scope rule documented in Connect Hosted MCP Tools — Scope And Visibility: a path containing /ingest requires groundx:ingest; any other write verb (POST, PUT, PATCH, DELETE) requires groundx:write; everything else requires groundx:read. If the connecting key’s granted scopes don’t include the scope a tool needs, that tool won’t appear.

2. Read-only visibility. A read-only (groundx:read-only) key only ever shows bucket_list, group_list, and health_get from the 12 default tools, plus the 4 always-present tools (groundx_account_context, list_operations, describe_operation, call_operation). Both search tools (search_content, search_documents) use POST and require groundx:write, so they’re correctly absent for a read-only key — not a bug. All ingest- and write-scoped default tools are likewise expected to be hidden. If you need those tools, upgrade the key’s granted scopes in the GroundX dashboard; a broader-scope key unlocks the corresponding tools on reconnect.

3. Old tool name migration. If you’re calling a tool by a name that used to work directly (for example a bare bucket_delete, document_delete, or a workflow/API-key management tool), that name no longer resolves. GroundX MCP now registers exactly 12 default tools plus 4 always-present tools — advanced and destructive operations are reached only through the discovery path:

   list_operations({})
   describe_operation({ "operationId": "Bucket_delete" })
   call_operation({ "operationId": "Bucket_delete", "args": { "bucketId": 12345 } })

   There is no restore flag. No configuration option, environment variable, or opt-in brings back the old full named-tool list (see Connect Hosted MCP Tools — Migration From Old Tool Names). Use list_operations to confirm the exact operationId — advanced operations use the PascalCase operationId form (for example Bucket_delete, Document_delete1), never the normalized lowercase form used by the 12 default tools. Scope enforcement still applies on this path: a read-only session gets a scope error for a write- or ingest-scoped operation called through call_operation, exactly as it would through a direct tool.

SDK/REST Fallback

Whether to use hosted MCP or the direct SDK/REST path depends on three factors: whether your client supports remote MCP/connectors at all, whether the MCP connection is actually available and connected, and whether the operation you need is covered by MCP’s tool surface. Fall back to the direct SDK/REST path (see Direct SDK/API Quickstart) instead of hosted MCP when:

• Your client doesn’t support remote MCP/connectors. Not every client has an MCP or connector surface — see the client support table in Install GroundX Agent Harness. If yours doesn’t, SDK/REST is the only option, not a fallback.
• MCP is unavailable or not connected. If prod MCP tools aren’t visible and you don’t specifically need MCP client setup, continue with SDK/REST rather than troubleshooting the connector first.
• You need an operation MCP doesn’t expose. Creating a new API key, for example, is hidden from list_operations and rejected by call_operation for every scope — it’s only available through the dashboard, SDK, or REST.

Evidence To Collect

Before escalating or filing a bug report, collect this checklist:

• Client name — for example Claude Code CLI, VS Code + Claude, Claude Code Desktop, Claude Desktop (connector-only), Codex CLI, or Codex Desktop.
• MCP URL — https://api.groundx.ai/mcp or the equivalent https://api.groundx.ai/api/v1/mcp (or the on-prem deployment’s equivalent hostname).
• Auth mode — OAuth (interactive browser flow) or X-API-Key transport (headless/CI).
• Visible tools — the tool list from the client, cross-checked against groundx_account_context and list_operations output.
• Scope/account context, without secrets — the resolved account type, mode, granted scopes, base URL, and enabled tool groups from groundx_account_context.
• Error text — the exact error message or HTTP status returned.

Never include the raw API key in a bug report — not in the client name, the MCP URL, the auth mode, the tool list, the account context, or the error text. If an error message echoes back a key or token, redact it before sharing.