GroundX MCP Integration Guide

GroundX supports the Model Context Protocol (MCP), allowing compatible AI agents and MCP clients to use the GroundX API through a standard tool interface.

The GroundX MCP endpoint exposes the GroundX APIs as MCP tools. After a client connects, it can discover tools for buckets, documents, groups, search, workflows, API keys, account information, and health checks. The agent can then call those tools when it needs to search content, ingest documents, inspect processing status, manage buckets, or perform other GroundX API operations.

Endpoint

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

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

The same endpoint is also reachable at https://api.groundx.ai/api/v1/mcp. Either URL is accepted.

Authentication

GroundX MCP uses the same API key authentication as the GroundX API.

Send your API key using the X-API-Key header:

1
X-API-Key: YOUR_API_KEY

HTTP-based MCP clients should also send:

1
Content-Type: application/json
2
Accept: application/json, text/event-stream

Some MCP clients do not support custom headers. Those clients are currently not supported.

How MCP Tools Map to GroundX APIs

GroundX MCP tools are generated from GroundX API operations. Tool names follow the API resource and action, such as bucket_list, document_ingestremote, search_content, or workflow_create.

Each tool includes an input schema and output schema exposed through MCP tool discovery. Compatible MCP clients should discover the available tools and their parameters automatically.

The current MCP tool surface includes GroundX tools for:

Because GroundX API operations are exposed as tools, MCP clients can support more than retrieval. For example, an agent can list buckets before searching, ingest a new document, check the ingest process, and then search the resulting content, all through MCP tool calls.

Tool Reference

The tool names, methods, paths, and required top-level arguments are:

Required arguments in this table are the top-level MCP tool arguments. Some object and array arguments have their own nested required fields. For example, document_ingestremote requires documents, and each document object requires bucketId and sourceUrl.

Walkthrough: Search Existing Content

A common MCP use case is allowing an agent to search GroundX-managed content for retrieval-augmented generation (RAG). GroundX exposes two search tools:

• search_content: searches a bucket ID, group ID, or document ID
• search_documents: searches a specific list of document IDs

Search by bucket, group, or document ID

Use search_content when the agent should search a GroundX bucket, group, or document.

1
{
2
  "id": 31,
3
  "query": "What does this document say about termination?",
4
  "n": 10
5
}

The id value can be a bucket ID, group ID, or document ID. The query value is the natural-language search query.

Search specific documents

Use search_documents when the agent should search an explicit set of document IDs.

1
{
2
  "documentIds": ["doc-id-1", "doc-id-2"],
3
  "query": "Summarize the renewal terms",
4
  "n": 10
5
}

Both search tools can return search.text, which is formatted for use as language model context, and search.results, which contains matching chunks for citations or custom display.

Search Tool Arguments

The search tools accept these common arguments:

Walkthrough: Inspect and Search a Bucket

An agent does not need the user to provide every ID up front if the API key has access to the relevant GroundX resources. It can use other GroundX tools first, then call search.

For example, an agent can:

1. Call bucket_list to find available buckets.
2. Choose the relevant bucket from the returned bucket list.
3. Call search_content with that bucket ID and the user’s query.
4. Use search.text as context for the final answer, or use search.results when citations are needed.

Example bucket_list call:

1
{
2
  "n": 20
3
}

Example search_content call after the agent selects bucket 31:

1
{
2
  "id": 31,
3
  "query": "Find the policy for data retention.",
4
  "verbosity": 2
5
}

Walkthrough: Ingest and Query a Document

Because GroundX MCP exposes ingest APIs as tools, an agent can also add content to GroundX before searching it.

For example, an agent can:

1. Call bucket_create or bucket_list to identify the destination bucket.
2. Call document_ingestremote to ingest a publicly accessible file.
3. Call document_getprocessingstatusbyid to check processing status, polling until status reaches complete or error.
4. Once processing is complete, call search_content or search_documents.

Example document_ingestremote call:

1
{
2
  "documents": [
3
    {
4
      "bucketId": 31,
5
      "sourceUrl": "https://example.com/handbook.pdf",
6
      "fileName": "handbook.pdf",
7
      "fileType": "pdf"
8
    }
9
  ]
10
}

The response includes a processId that the agent uses to poll for completion.

Ingest is asynchronous

document_ingestremote, document_crawlwebsite, document_update, documents_copy, and documents_delete all return a processId immediately and process in the background. Newly ingested documents are not searchable until processing completes. Agents should poll document_getprocessingstatusbyid with the returned processId until ingest.status reaches one of:

A reasonable polling interval is five seconds. Search calls issued before complete will not include the new content.

Local files

The GroundX MCP server does not expose a tool for local-file uploads. To make a local file available to MCP, upload it to GroundX-hosted storage via the pre-signed URL service first, then submit the resulting hosted URL to document_ingestremote. This pattern matches the 25–50 MB per-file limit and the 50-file batch capacity of remote ingest.

Workflow Tools

Workflows control the processing pipeline applied during ingest — chunking strategy, section strategy, custom LLM steps, and extract agent definitions. The 10 workflow_* MCP tools cover workflow CRUD plus assigning a workflow to the account, a bucket, or a group.

Workflow assignments are layered. More specific assignments override broader ones:

1. Account level — workflow_add_to_account sets a default workflow for every ingest in the account.
2. Group or bucket level — workflow_add_to_id overrides the account default for content ingested into that group or bucket.
3. Document level — the document’s processLevel field (full or none) controls how much processing happens for that single ingest.

Reading the current state is symmetric: workflow_get_account returns the account-level assignment, and workflow_get with a groupId, bucketId, or workflowId returns the workflow at that scope.

Pre-Flight Health Check Pattern

The health_list and health_get tools return current service health. Statuses update every five minutes. Calling health_list before a large ingest run is a cheap way to short-circuit a workload when an upstream service is degraded. Each entry returns service, status (healthy, degraded, down, or unknown), and lastUpdate.

Client Configuration

Currently, clients must support HTTP headers. Configure your client with the MCP server URL and API key header:

1
{
2
  "url": "https://api.groundx.ai/mcp",
3
  "headers": {
4
    "X-API-Key": "YOUR_API_KEY",
5
    "Accept": "application/json, text/event-stream"
6
  }
7
}

Notes

• GroundX MCP exposes GroundX API operations as MCP tools, not only search.
• The available tools and schemas are returned through MCP tool discovery.
• Tool access is scoped by the API key used to connect to MCP.
• The apikey_* tools manage API keys for the account; treat them as administrative and do not expose them to end-user agents.
• Use search_content when searching a bucket, group, or document ID.
• Use search_documents when searching a specific list of document IDs.
• Include Accept: application/json, text/event-stream for HTTP-based MCP requests.