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.

Installing the skills and connecting the hosted MCP tools are independent: installing the skills does not connect the tools, and connecting the tools does not install the skills. Set up whichever you need. In the steps below, “the plugin” means the skills bundle you install, not the whole harness.

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 MCP (optional):

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

Run /mcp, connect groundx, enter your key on the GroundX sign-in page, and start a new Claude Code session.

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.

Connecting MCP is a separate, optional step: open Settings -> MCP servers, add a server, toggle it to Streamable HTTP, and enter URL https://api.groundx.ai/mcp. The saved MCP server entry in the MCP server list should show an Authenticate button; click it and enter your key on the GroundX sign-in page.

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.

Connecting MCP is a separate, optional step:

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

Then run /mcp, connect groundx, enter your key on the GroundX sign-in page, and start a new session.

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

Connecting MCP is a separate, optional step:

1codex mcp add groundx --url https://api.groundx.ai/mcp
2codex mcp login groundx

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. Connecting MCP is optional and uses the same commands as the CLI sections above; enter your key on the GroundX sign-in page.

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