Install GroundX Agent Harness | Documentation

Install GroundX Agent Harness, optionally connect the hosted MCP tools, then verify the setup. The plugin source is GroundX-Studio/groundx-agent-harness on GitHub.

GroundX Agent Harness uses the open Agent Skills (SKILL.md) standard. Claude and Codex install it as a plugin. Other agents (Cursor, Replit, Gemini, Windsurf, Copilot, and more) use their own Agent Skills installation method. This may mean running an install command or adding the repository’s skills/ folder. See your agent’s documentation for the steps.

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. Use the full URL or shorthand shown for your client 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.

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:

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 manifest. Set owner to your organization and source to the bundle’s path in the repository. Keep the plugin’s description, strict, and skills fields. You may set author to your approved organization publisher:

{
  "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):

Open Settings -> Connectors -> + -> Add custom connector. From the Code tab the route is Customize -> Connectors.
Enter Name: GroundX API and MCP URL https://api.groundx.ai/mcp.
Leave the advanced OAuth fields empty unless Claude asks you to review discovered settings.
Click Add, then Connect.
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:

Open Plugins -> Manage (or Manage marketplaces).
Add a marketplace from https://github.com/GroundX-Studio/groundx-agent-harness, ref main, leaving sparse paths empty.
Install GroundX Agent Harness.
Start a new Codex session.

Connect the hosted MCP tools (optional):

Open Settings -> Plugins.
Find groundx in the list and click Authenticate.
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:

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:

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

Codex CLI

Install the plugin:

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:

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:

codex plugin list
codex mcp list

VS Code

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

Claude Code:

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

Codex:

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

For other agents that support Agent Skills, including Cursor, Replit, Gemini, Windsurf, and Copilot:

Clone the harness:

git clone https://github.com/GroundX-Studio/groundx-agent-harness

Add its skills/ folder to your agent’s skills directory. See your agent’s docs for where skills live.
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:

node scripts/doctor.mjs

To check a specific client or connection, pass its name as an argument, 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.
Ready to put it to work? See Use GroundX With Your Agent.