Connect Hosted GroundX MCP Tools

GroundX supports the Model Context Protocol (MCP): compatible AI agents and MCP clients call GroundX APIs through a standard tool interface. Hosted GroundX MCP is optional — you can integrate with GroundX entirely through the direct SDK/API path instead. Whether hosted MCP fits your case depends on: whether your client supports remote MCP/connectors, whether the connection is available, and whether the operation you need is in MCP’s tool surface (hosted GroundX MCP is production-only today). See SDK/REST Fallback for the full breakdown.

This page covers the endpoint, authentication, the current default tool surface, and how to reach advanced operations that aren’t registered as named tools.

Setup

Endpoint

Configure your MCP client to connect to the GroundX MCP endpoint:

1
https://api.groundx.ai/mcp

The same server is also reachable at the equivalent path:

1
https://api.groundx.ai/api/v1/mcp

Either URL works — use whichever form your client’s configuration expects.

For authenticated GroundX operations, connect to the product endpoint https://api.groundx.ai/mcp (this page). A separate docs-search endpoint at https://docs.groundx.ai/_mcp/server exists only to give AI clients context about these docs; it cannot perform GroundX account operations, so do not use it for product tools.

Authentication

GroundX MCP supports two auth paths:

• OAuth — for interactive clients that can open a browser (for example Claude Desktop or Codex Desktop). The client discovers OAuth metadata, redirects to a GroundX-hosted authorization page, and receives short-lived MCP tokens. You never handle a raw key in this flow after the initial authorization.
• X-API-Key transport — for headless or non-interactive clients (for example Claude Code CLI, Codex CLI, Cursor, Replit, or CI runners). The key is sent as an X-API-Key HTTP header on the MCP transport connection:

1
{
2
  "mcpServers": {
3
    "groundx": {
4
      "url": "https://api.groundx.ai/mcp",
5
      "headers": {
6
        "X-API-Key": "${GROUNDX_API_KEY}"
7
      }
8
    }
9
  }
10
}

Never place a raw API key inside a tool argument. The key belongs only in the transport-layer header or the OAuth flow — never in call_operation, search_content, or any other tool call payload.

Tool Surface

Default Tools

A regular customer key sees the 12 default tools below. Which are visible in a given session depends on the scopes granted to the connecting API key (see Scope and Visibility below), so a higher-scope key (for example a Partner-tier key) may register additional tools beyond this set.

Always call these tools using the normalized lowercase name shown in the left column (for example document_ingestremote), never a PascalCase operationId form.

Always-Present Tools

In addition to the 12 default tools, 4 tools are always registered regardless of the session’s granted scopes:

• groundx_account_context
• list_operations
• describe_operation
• call_operation

list_operations, describe_operation, and call_operation are the 3 discovery meta-tools that make advanced operations reachable. groundx_account_context takes no input and returns the resolved account type, mode, granted scopes, base URL, and enabled tool groups for the current session.

Scope And Visibility

Tool visibility is governed by a derived-scope rule, operationAllowedByScopes(path, method), applied both when filtering visible default tools and inside call_operation before dispatch:

1. If the path contains /ingest → the required scope is groundx:ingest.
2. Otherwise, if the method is a write verb (POST, PUT, PATCH, or DELETE) → the required scope is groundx:write.
3. Otherwise → the required scope is groundx:read.

Both search tools (search_content, search_documents) use POST, so they require groundx:write, not groundx:read — this is intentional.

A session granted only groundx:read sees a reduced set of the 12 default tools — only the tools whose derived scope is groundx:read:

• bucket_list
• group_list
• health_get

All ingest-scoped and write-scoped default tools, including both search tools, are hidden in a read-only session. The 4 always-present tools are present regardless of scope, but call_operation still enforces operationAllowedByScopes before dispatch — a read-only session can’t execute write or ingest operations through it either.

The visible tools always follow the connecting key’s scopes: a narrower key sees fewer of the 12 default tools, and a higher-scope key (such as a Partner-tier key) registers additional tools beyond them.

Advanced Operations

Operations outside the default 12 — including bucket deletion, document deletion, workflow management, and API key management — aren’t registered as named MCP tools. Reach them through the three always-present discovery meta-tools, in order:

1. list_operations({}) — returns every operation exposed through MCP discovery, each with its operationId, method, path, summary, and description.
2. describe_operation({ "operationId": "<id>" }) — returns the full parameter schema (parameters[] and inputSchema) for one operation, so you can build a valid args object.
3. call_operation({ "operationId": "<id>", "args": { ... } }) — executes the operation and returns the proxied GroundX API result.

1
call_operation({
2
  "operationId": "Bucket_delete",
3
  "args": { "bucketId": 12345 }
4
})

The argument name is operationId in both describe_operation and call_operation — never operation_id. This is a common mistake; the underscored form doesn’t work.

Scope enforcement still applies inside call_operation, using the same derived-scope rule described above. A session with only groundx:read gets a scope error if it attempts a write- or ingest-scoped operation this way — discovery doesn’t bypass scope checks. A few operations are further restricted regardless of scope: managing existing API keys (listing, updating, or deleting) requires groundx:admin, and creating a new API key isn’t available through MCP at all — it’s hidden from list_operations and rejected by call_operation for every scope.

Usage Notes

Ingest And Search Workflow

The default tools above cover the standard bucket-create, ingest, poll, and search sequence for retrieval-augmented generation. For a full walkthrough of building an agent-driven RAG workflow on top of GroundX MCP, see Ingest, Search, and Answer With an Agent.

Local Files

The GroundX MCP server doesn’t expose a tool for local-file uploads. To make a local file available through MCP, upload it to GroundX-hosted storage via the pre-signed upload flow first, then submit the resulting hosted URL to document_ingestremote.

If you’re integrating from application code rather than an MCP client, the GroundX SDKs handle this pre-signed upload flow automatically — see GroundX SDKs and the in-depth ingest guide for the direct-SDK equivalent.

Migration From Old Tool Names

GroundX MCP previously registered the full GroundX API surface directly as named tools. That default is now reduced to the 12 default tools plus the 4 always-present tools documented above. This is a breaking change for any client that called an advanced or destructive operation by its old direct tool name (for example a bare bucket_delete or workflow_delete tool call).

There is no restore flag. No configuration option, environment variable, or opt-in brings back the old full named-tool list — the simplified default surface is intentional and permanent.

If you relied on an operation that’s no longer directly registered, use the discovery path instead:

list_operations({})
describe_operation({ "operationId": "Bucket_delete" })
call_operation({ "operationId": "Bucket_delete", "args": { "bucketId": 12345 } })

Use list_operations to confirm the exact operationId for the operation you need — advanced operation names use the PascalCase operationId form (for example Bucket_delete, Document_delete1), never the normalized lowercase form used by the 12 default tools.