Connect Hosted GroundX MCP Tools

Connect your agent or app to GroundX through the Model Context Protocol (MCP), a standard for calling tools from AI clients. Your client must support remote MCP, and GroundX must expose the operation you need. You can also call GroundX from code through the Direct SDK/API Quickstart. See SDK/REST Fallback for connection and tool limitations.

Setup

Endpoint

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

https://api.groundx.ai/mcp

The same server is also reachable at the equivalent path:

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

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

Authentication

GroundX MCP supports two auth paths:

• OAuth: for interactive clients that can open a browser (for example Claude Desktop or Codex Desktop). Sign in on the GroundX authorization page. The client then uses short-lived MCP tokens, without requiring the key again.
• 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:

{
  "mcpServers": {
    "groundx": {
      "url": "https://api.groundx.ai/mcp",
      "headers": {
        "X-API-Key": "${GROUNDX_API_KEY}"
      }
    }
  }
}

Keep API keys in the connection’s HTTP header or OAuth sign-in flow. Never put them in call_operation, search_content, or any other tool’s arguments.

Available Tools

Default Tools

A customer key can access the 12 tools below, subject to its permissions (scopes). Partner keys may expose additional tools. See Scope and Visibility.

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

Use list_operations, describe_operation, and call_operation to find and run advanced operations. groundx_account_context takes no input and returns the account type, mode, scopes, base URL, and enabled tool groups.

Local-File Upload Tool

document_uploadlocal requires groundx:ingest, as does document_ingestremote. It is separate from the 12 default tools and cannot be called through call_operation by its tool name. Pass bucketId, fileName and fileType to use the authenticated bucket upload operation. It returns a URL, HTTP method, header map, hosted URL and expiry. The same operation is available through discovery as Buckets_fileUpload.

The MCP host must read the local file and send its bytes by HTTP PUT. A client that can only call tools cannot complete the upload.

Use the header entries as follows:

• Host: the S3 upload host; HTTP clients normally set this automatically from url, so no action is usually needed.
• GX-HOSTED-URL (if present): the same value as hostedUrl. Use it as sourceUrl later. Do not send it as an S3 header.
• Any other entries: send them as request headers on the PUT.

See Local Files below for the full flow.

Scope And Visibility

Your key’s scopes control which tools appear and which operations call_operation can run:

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.

A session with only groundx:read sees three of the default tools:

• bucket_list
• group_list
• health_get

Ingest and write tools, including search, are hidden in a read-only session. The four always-present tools remain visible, but call_operation still rejects write and ingest calls. document_uploadlocal is visible only with groundx:ingest.

Advanced Operations

For bucket or document deletion, workflows, file access, and existing API keys, find and call operations in this 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.

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

Use operationId in both describe_operation and call_operation. operation_id is not accepted.

call_operation enforces the same scopes as direct tools. Listing, updating, or deleting existing API keys also requires groundx:admin. Creating API keys is unavailable through MCP for every scope: it is hidden from list_operations and rejected by call_operation.

Usage Notes

Ingest And Search Workflow

Create a bucket, ingest documents, wait for processing, then search. For a walkthrough, see Use GroundX With Your Agent.

Local Files

Your MCP host must read local files and send HTTP PUT requests to complete this flow. Otherwise, upload through application code using the SDK/API below.

For public or protected staging, call document_uploadlocal({ "bucketId": 1234, "fileName": "...", "fileType": "..." }) to get a pre-signed upload target, PUT the file’s bytes to the returned url (sending the required header entries; see Local-File Upload Tool above for which ones), then call document_ingestremote with the returned hostedUrl as sourceUrl. This matches how the Python SDK’s client.ingest() handles local files internally.

document_uploadlocal({ "bucketId": 1234, "fileName": "invoice", "fileType": "pdf" })
// → {
//     "url": "https://eyelevel-upload.s3.us-west-2.amazonaws.com/...",
//     "method": "PUT",
//     "header": {
//       "Host": ["eyelevel-upload.s3.us-west-2.amazonaws.com"],
//       "Gx-Hosted-Url": ["https://upload.eyelevel.ai/prod/file/ssp/....pdf"]
//     },
//     "hostedUrl": "https://upload.eyelevel.ai/prod/file/ssp/....pdf"
//   }

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.

File Policies, Private Upload and Sharing

File policies, private uploads, and sharing require a compatible server deployment with file gateway and storage support. Call groundx_account_context, then list_operations, and inspect each operation with describe_operation before using it. Use its API operationId through discovery.

Request fields are flattened into args, not nested under body:

{
  "operationId": "Bucket_update",
  "args": {"bucketId": 1234, "fileAccess": {"mode": "protected"}, "fileAccessRevision": 0}
}

Pass this object to call_operation after inspecting the schema. Before updating, read the current revision with GET. Send that revision with fileAccess: null to clear an override; omit fileAccess to leave it unchanged. A document policy update uses the documents array with one item containing only the document ID and policy fields. A stale revision returns 409. If you receive 503, do not assume protection was applied.

On compatible servers, bucket_create accepts initial fileAccess, and each document_ingestremote item or crawl input can have its own policy. Omit the policy or set it to null to inherit. Creation needs no previous revision, and account or bucket restrictions still apply. For protected local files, including one in a public bucket, discover and call:

{
  "operationId": "Buckets_fileUpload",
  "args": {"bucketId": 1234, "fileName": "invoice.pdf", "fileType": "pdf", "fileAccess": {"mode": "protected"}}
}

Include the requested per-file policy in upload issuance and ingest. The API checks it before returning a grant; a disabled deployment returns 403 before bytes can be sent.

The tool returns upload instructions, not an uploaded file. The host must send the bytes to uploadUrl using the returned method and required headers, without GroundX credentials. Then submit hostedUrl through document_ingestremote in the same bucket, with the requested policy. If the reservation expires, reserve and upload again. document_uploadlocal with bucketId uses this same issuer for public and protected files. Calls without bucketId retain the legacy anonymous adapter and must not be used for protected files. Both forms use the configured API and storage, including on-prem, without a hosted broker fallback. Upload issuance remains available with read protection disabled. The host must be able to read files and send HTTP requests.

To share a saved page, discover Documents_fileLink and call:

{
  "operationId": "Documents_fileLink",
  "args": {"documentId": "11111111-1111-4111-8111-111111111111", "asset": {"kind": "page", "pageNumber": 1}, "expiresInSeconds": 120}
}

Recipients can use the returned url unchanged until expiresAt, without a GroundX key. Refresh expired citations through authorized search or a new link request. To read protected stable URLs or X-Ray ?view=links, a trusted server must send the owner’s X-API-Key. MCP OAuth tokens do not authorize these reads. For delegated Partner calls, keep the same selected customer and follow the discovered schema; customer membership checks still apply. See File Access and Sharing for inheritance, raw X-Ray, expiry, errors, and on-prem requirements.