Agent Harness

Install GroundX Agent Harness

This page covers installing GroundX Agent Harness for each supported client, connecting the optional hosted MCP server, and verifying the install. The public 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; any other skills-capable agent (Cursor, Replit, Gemini, Windsurf, Copilot, and more) uses the same portable skills by adding the repository’s skills/ folder. Installing the skills is the primary step; the hosted MCP server is a separate, optional add-on.

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 public repo. 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 endpoint, if you plan to connect it: https://api.groundx.ai/mcp. It is optional and prod-only today.

The plugin/skills, GROUNDX_API_KEY, and MCP are three separate pieces. Installing the plugin does not set up API access, and connecting MCP does not install the plugin. Set up whichever of the three you actually need. As in What Is GroundX Agent Harness?, “the plugin” below means just one of these three pieces (the instructions, references, and workflows), not the whole harness.

Client support:

ClientPlugin / skillsMCP API tools
Claude DesktopYesYes
Claude Desktop with Connectors onlyNo plugin skills; use hosted connector for MCP toolsYes
Codex DesktopYesYes
Claude CLIYesYes
Codex CLIYesYes
VS CodeYesYes
Everything else (Cursor, Replit, Gemini, Windsurf, Copilot, and more)Yes, via the portable skills/ folderIf your agent supports remote MCP

Claude Desktop

Most Claude app builds expose the Plugins/Cowork surface and install the plugin from a marketplace. Builds that expose only Connectors use the connector-only path below.

Install the plugin (personal marketplace). No GitHub account is needed for this public repo. 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 public repo is not supported as the direct organization marketplace sync target. Vendor or copy the public 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 public 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.

Claude Desktop with Connectors only

Builds that only expose Connectors (no Plugins/Cowork surface) have no plugin skills; the connector only provides MCP API tools.

Go to Customize -> Connectors, click +, then Add custom connector, and enter:

Name: GroundX API
Remote MCP Server URL: https://api.groundx.ai/mcp

Add the connector first, then connect/authorize on the next screen; these are separate steps. Leave advanced OAuth fields empty unless Claude asks you to review discovered settings. Enter your key on the GroundX sign-in page, then enable the connector in a conversation.

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