> 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. # Install GroundX Agent Harness This page covers installing GroundX Agent Harness for each supported client, connecting the optional hosted MCP tools, and verifying the install. The plugin source is [`GroundX-Studio/groundx-agent-harness`](https://github.com/GroundX-Studio/groundx-agent-harness) on GitHub. GroundX Agent Harness is built on the open Agent Skills (`SKILL.md`) standard. Claude and Codex install it as a one-command plugin. Other skills-capable agents (Cursor, Replit, Gemini, Windsurf, Copilot, and more) install the same skills however that agent supports Agent Skills, which may be an install command or adding the repository's `skills/` folder; see your agent's own docs for the exact step. Installing the skills is the main step. Connecting the hosted MCP tools is an optional enhancement you can add later. ## Before You Start * **A GroundX API key.** Sign in or create an account at `https://dashboard.groundx.ai`, then create or copy an API key. Wherever you enter it, use the GroundX sign-in page, an environment variable, or an approved local secret store. Never paste an API key into chat or a tool argument. * **The repository.** Install commands and marketplace prompts reference [`GroundX-Studio/groundx-agent-harness`](https://github.com/GroundX-Studio/groundx-agent-harness). Some clients want the full URL, others the shorthand `GroundX-Studio/groundx-agent-harness`; both are called out below. * **The hosted MCP address**, if you plan to connect it: `https://api.groundx.ai/mcp`. On Claude Code and Codex, the plugin registers the hosted MCP server. Sign in to use the tools. Claude Desktop and Cowork do not read plugin MCP config, so add the server there as a connector. In the steps below, "the plugin" means the skills bundle you install, not the whole harness. > **Note** > > A `groundx` server you configure yourself is a second copy of the one the plugin > registers, so its tools appear twice. Keep the `plugin:` entry and remove yours. **Client support:** | Client | Skills | Hosted MCP tools | | --------------------------------------------------------------------- | ------------------------------------------------------- | --------------------------------- | | Claude Desktop | Yes | Yes | | Codex Desktop | Yes | Yes | | Claude CLI | Yes | Yes | | Codex CLI | Yes | Yes | | VS Code | Yes | Yes | | Everything else (Cursor, Replit, Gemini, Windsurf, Copilot, and more) | Yes, installed however your agent supports Agent Skills | If your agent supports remote MCP | ## Claude Desktop Install the plugin from a marketplace: **Install the plugin (personal marketplace).** No GitHub account is needed. Go to **Customize -> Plugins -> Personal plugins + -> Add marketplace -> Add from a repository**, and enter: ```text GroundX-Studio/groundx-agent-harness ``` If the repository list cannot load, type `GroundX-Studio/groundx-agent-harness` directly. Click **Sync**, install **GroundX Agent Harness**, then run `/reload-plugins` or start a new session. **Organization distribution (Team/Enterprise admins).** Claude organization GitHub sync uses a private or internal marketplace repository; the `GroundX-Studio/groundx-agent-harness` repository is not supported as the direct organization marketplace sync target. Vendor or copy the bundle into your organization's private marketplace repository at `plugins/groundx-agent-harness/`. The private marketplace repository should include: ```text .claude-plugin/marketplace.json plugins/groundx-agent-harness/.claude-plugin/marketplace.json plugins/groundx-agent-harness/README.md plugins/groundx-agent-harness/scripts/ plugins/groundx-agent-harness/skills/ ``` Create the root `.claude-plugin/marketplace.json` with a complete marketplace manifest. Use your organization for the root `owner`, keep the bundle plugin entry's `description`, `strict`, and `skills` fields, and change only the plugin `source` to the repo-relative path. You may replace `author` with your approved organization publisher value: ```json { "name": "groundx-agent-harness-marketplace", "owner": { "name": "Your Organization" }, "plugins": [ { "name": "groundx-agent-harness", "description": "GroundX agent runtime harness for API use, schema-first extraction, on-prem deployment, architecture, and supported GTM guidance.", "author": { "name": "GroundX" }, "source": "./plugins/groundx-agent-harness", "strict": false, "skills": [ "./skills/groundx-api", "./skills/groundx-mcp", "./skills/groundx-extraction-workflows", "./skills/groundx-on-prem", "./skills/groundx-architecture", "./skills/product-brand-gtm", "./skills/master-brand-gtm", "./skills/groundx-python" ] } ] } ``` After an admin completes the organization sync, users install GroundX Agent Harness from Claude **Cowork** or **Code** (the organization's plugin list), then run `/reload-plugins` or start a new session. **Connect the hosted MCP tools** (optional): 1. Open **Settings -> Connectors -> + -> Add custom connector**. From the Code tab the route is **Customize -> Connectors**. 2. Enter `Name: GroundX API` and MCP URL `https://api.groundx.ai/mcp`. 3. Leave the advanced OAuth fields empty unless Claude asks you to review discovered settings. 4. Click **Add**, then **Connect**. 5. Enter your key on the GroundX sign-in page. If GroundX tools show up twice in Claude Code afterwards, see "GroundX Tools Appear Twice" in [Verify and Troubleshoot](/documentation/agent-harness/verify-and-troubleshoot). ## Codex Desktop Install the plugin first: 1. Open **Plugins -> Manage** (or **Manage marketplaces**). 2. Add a marketplace from `https://github.com/GroundX-Studio/groundx-agent-harness`, ref `main`, leaving sparse paths empty. 3. Install **GroundX Agent Harness**. 4. Start a new Codex session. **Connect the hosted MCP tools** (optional): 1. Open **Settings -> Plugins**. 2. Find `groundx` in the list and click **Authenticate**. 3. Enter your key on the GroundX sign-in page. If `groundx` is not in the list, add it: **Settings -> Plugins -> Add -> Add MCP server**, type **Streamable HTTP**, URL `https://api.groundx.ai/mcp`, **Save**, then **Authenticate**. ## Claude CLI Install the plugin: ```sh claude plugin marketplace add GroundX-Studio/groundx-agent-harness claude plugin install groundx-agent-harness@groundx-agent-harness ``` Run `/reload-plugins` or start a new session after installing. If `claude plugin` is not found, update Claude Code first. The plugin registers the server as `plugin:groundx-agent-harness:groundx`. Run `/mcp`, connect `groundx`, and enter your key on the GroundX sign-in page, or set `GROUNDX_API_KEY` before starting Claude Code. If it is missing from `claude mcp list`, add it: ```sh claude mcp add --transport http groundx https://api.groundx.ai/mcp ``` ## Codex CLI Install the plugin: ```sh codex plugin marketplace add GroundX-Studio/groundx-agent-harness --ref main codex plugin add groundx-agent-harness@groundx-agent-harness ``` The plugin registers the hosted server. Sign in: ```sh codex mcp login groundx ``` Setting `GROUNDX_API_KEY` in the environment Codex runs in works instead. If `groundx` is missing from `codex mcp list`, add it with `codex mcp add groundx --url https://api.groundx.ai/mcp`. Verify and start a new Codex session: ```sh codex plugin list codex mcp list ``` ## VS Code Open the VS Code integrated terminal and run the install for your agent. Claude Code: ```sh claude plugin marketplace add GroundX-Studio/groundx-agent-harness claude plugin install groundx-agent-harness@groundx-agent-harness ``` Codex: ```sh codex plugin marketplace add GroundX-Studio/groundx-agent-harness --ref main codex plugin add groundx-agent-harness@groundx-agent-harness ``` Then reload plugins or start a new session. If `claude plugin` is not found, update Claude Code first. Both plugins register the hosted server. Sign in with `/mcp` in Claude Code, or `codex mcp login groundx` in Codex. ## Everything else The harness works on any skills-capable agent (Cursor, Replit, Gemini, Windsurf, Copilot, and more) through the open Agent Skills (`SKILL.md`) standard. 1. Clone the harness: ```sh git clone https://github.com/GroundX-Studio/groundx-agent-harness ``` 2. Add its `skills/` folder to your agent's skills directory. See your agent's docs for where skills live. 3. Reload or restart your agent so it picks up the skills. If your agent supports remote MCP, you can also add the optional tools: in your agent's MCP settings, add a Streamable HTTP server with URL `https://api.groundx.ai/mcp`, authenticate, and enter your key on the GroundX sign-in page. ## Verify Run these checks without pasting secrets into chat: ```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 ``` You can pass a specific client or check name as an argument to scope the check, for example `node scripts/doctor.mjs vscode-claude` or `node scripts/doctor.mjs mcp`. ## Next Steps * If a verification check above didn't behave as expected, see [Verify and Troubleshoot](/documentation/agent-harness/verify-and-troubleshoot). * Ready to put it to work? See [Use GroundX With Your Agent](/documentation/agent-harness/ingest-search-and-answer-with-an-agent).