Connect Hosted GroundX MCP Tools

This page is for connecting your AI agent (or your own app) to GroundX’s hosted tools, so it can do GroundX work for you. It covers the address to connect to, how to sign in, which tools you get, and how to reach the more advanced ones.

GroundX supports the Model Context Protocol (MCP), a standard way for AI agents and other clients to call GroundX through a set of ready-made tools. Connecting these hosted tools is optional; you can also work with GroundX entirely from your own code through the Direct SDK/API Quickstart. Whether the hosted tools fit depends on: whether your client supports remote MCP or connectors, whether the connection is available, and whether the tool you need is one of the ones GroundX makes available. See SDK/REST Fallback for the full breakdown.

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

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.

Available Tools

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

Which tools you see depends on your key’s permissions. The rule that decides this, 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 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 answering questions from your own documents. For a full walkthrough of building an agent-driven workflow that answers questions from your documents on top of GroundX’s hosted tools, see Use GroundX With Your 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.