Agent Harness

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 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. 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.

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:

ClientSkillsHosted MCP tools
Claude DesktopYesYes
Codex DesktopYesYes
Claude CLIYesYes
Codex CLIYesYes
VS CodeYesYes
Everything else (Cursor, Replit, Gemini, Windsurf, Copilot, and more)Yes, installed however your agent supports Agent SkillsIf 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:

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:

.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:

1{
2  "name": "groundx-agent-harness-marketplace",
3  "owner": {
4    "name": "Your Organization"
5  },
6  "plugins": [
7    {
8      "name": "groundx-agent-harness",
9      "description": "GroundX agent runtime harness for API use, schema-first extraction, on-prem deployment, architecture, and supported GTM guidance.",
10      "author": {
11        "name": "GroundX"
12      },
13      "source": "./plugins/groundx-agent-harness",
14      "strict": false,
15      "skills": [
16        "./skills/groundx-api",
17        "./skills/groundx-mcp",
18        "./skills/groundx-extraction-workflows",
19        "./skills/groundx-on-prem",
20        "./skills/groundx-architecture",
21        "./skills/product-brand-gtm",
22        "./skills/master-brand-gtm",
23        "./skills/groundx-python"
24      ]
25    }
26  ]
27}

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.

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:

1claude plugin marketplace add GroundX-Studio/groundx-agent-harness
2claude 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:

1claude mcp add --transport http groundx https://api.groundx.ai/mcp

Codex CLI

Install the plugin:

1codex plugin marketplace add GroundX-Studio/groundx-agent-harness --ref main
2codex plugin add groundx-agent-harness@groundx-agent-harness

The plugin registers the hosted server. Sign in:

1codex 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:

1codex plugin list
2codex mcp list

VS Code

Open the VS Code integrated terminal and run the install for your agent.

Claude Code:

1claude plugin marketplace add GroundX-Studio/groundx-agent-harness
2claude plugin install groundx-agent-harness@groundx-agent-harness

Codex:

1codex plugin marketplace add GroundX-Studio/groundx-agent-harness --ref main
2codex 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:

    1git 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:

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:

1node 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