Verify And Troubleshoot GroundX Agent Harness | Documentation

Verify your setup after installing GroundX Agent Harness or connecting hosted MCP tools. Never paste an API key into chat.

Verify The Plugin

If you connected hosted MCP tools without installing the skills, go to Verify Hosted MCP.

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:

node scripts/doctor.mjs

If the plugin or its skills are missing, reload or start a new session:

Claude Desktop / Claude Code CLI / VS Code + Claude / Claude Code Desktop: run /reload-plugins, or start a new session.
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, confirm the connected account first:

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

This calls groundx_account_context (see Connect Hosted MCP Tools). It takes no input and returns the account type, mode, permissions (scopes), base URL, and enabled tool groups without secrets.

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

A regular user key shows ingest, search, bucket/group, and health tools allowed by its scopes. If it shows partner- or admin-only tools, report the bug with the account context and visible tool list (see Evidence To Collect).

GroundX Tools Appear Twice

Symptoms: every GroundX tool is listed twice, or the client asks for approval twice for one call.

Two copies of the server are attached. List them with claude mcp list or codex mcp list, then remove the entry that is not the plugin’s.

Entry	Source	Remove
`plugin:groundx-agent-harness:groundx`	The plugin	Keep this one
`claude.ai` prefix, such as `claude.ai GroundX`	A connector on your Claude account. `claude mcp remove` cannot delete it	Settings -> Connectors
Bare `groundx`	Added from a terminal	`claude mcp remove groundx` or `codex mcp remove groundx`

401 Or Reauthentication Required

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

Cause	Fix
No key configured, or `GROUNDX_API_KEY` not set in the environment	Set the environment variable, or connect through the client’s OAuth/connector flow. See Install GroundX Agent Harness for per-client steps
Revoked key	Generate a new key under API Keys at `https://dashboard.groundx.ai`
Expired OAuth token	Previously working sessions can return 401 once a short-lived MCP token expires. Re-authorize through the client UI. The raw key is not re-entered unless the token was fully revoked

Check the key directly through REST:

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

If a tool is missing, check these in order:

Scope mismatch. Which tools are visible follows your key’s permissions, 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.
Read-only visibility. A key with only groundx:read 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. Ingest tools require groundx:ingest. Add the required scopes in the GroundX dashboard, then reconnect.
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), use discovery to check the supported operation. GroundX MCP lists 12 default tools plus 4 always-present tools for ordinary customer sessions. Advanced and destructive operations use the discovery path:
```
list_operations({})
describe_operation({ "operationId": "Bucket_delete" })
call_operation({ "operationId": "Bucket_delete", "args": { "bucketId": 12345 } })
```
Some servers also support older direct names as aliases, but these do not appear in the default list. Use discovery to check availability and the current schema (see Connect Hosted MCP Tools: Advanced Operations). 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: call_operation rejects write or ingest operations in a read-only session.

SDK/REST Fallback

Use the Direct SDK/API Quickstart 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.
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

Include these details in a bug report:

Client name: for example Claude Desktop, Claude Code CLI, VS Code + Claude, Claude Code Desktop, 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 an API key or token in a bug report. Redact any secrets from error messages before sharing.

Protected Files or Expired Citations

To read a protected stable URL, a trusted server must send the owning account’s X-API-Key to the file host. MCP OAuth does not authorize that read; keep API keys out of browser code. Refresh expired links through authorized search, Documents_fileLink, or the X-Ray ?view=links URL. Do not retry anonymously or upload protected files to public staging. For 409, read the current settings and revision before deciding on an update. For 503, check that file protection is ready and wait for any Retry-After delay. See File Access and Sharing.