> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.eyelevel.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.eyelevel.ai/_mcp/server. # Verify And Troubleshoot GroundX Agent Harness Use this page after installing GroundX Agent Harness (see [Install GroundX Agent Harness](/documentation/agent-harness/install-ground-x-agent-harness)) or connecting hosted MCP (see [Connect Hosted MCP Tools](/documentation/agent-harness/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 the hosted MCP tools and never installed the skills, skip this section. There are no skills to verify. Go to [Verify Hosted MCP](#verify-hosted-mcp) instead. Run these checks without pasting secrets into chat. They're the same prompts from [Install GroundX Agent Harness](/documentation/agent-harness/install-ground-x-agent-harness): ```text List the GroundX Agent Harness skills you have available. ``` ```text Use the GroundX Agent Harness references to explain the safest document ingest -> status polling -> search flow. Do not ask me for an API key. ``` ```text 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: ```sh 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 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](/documentation/agent-harness/install-ground-x-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: ```text 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](/documentation/agent-harness/connect-hosted-mcp-tools#always-present-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. ```text 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 set of default tools (ingest, search, bucket/group management, health; scoped per [Scope And Visibility](/documentation/agent-harness/connect-hosted-mcp-tools#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](#evidence-to-collect)) and escalate it rather than treating it as a working state. ## 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](/documentation/agent-harness/install-ground-x-agent-harness) for per-client steps | | Revoked key | Generate a new key at `https://dashboard.groundx.ai` → API Keys | | 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 | A quick REST sanity check confirms whether the key is the problem, independent of the MCP layer: ```sh 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.** Which tools are visible follows your key's permissions, documented in [Connect Hosted MCP Tools: Scope And Visibility](/documentation/agent-harness/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: ```text 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: Advanced Operations](/documentation/agent-harness/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 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 the tools MCP makes available. Fall back to the direct SDK/REST path (see [Direct SDK/API Quickstart](/documentation/get-started/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](/documentation/agent-harness/install-ground-x-agent-harness#before-you-start). 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 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 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.