GroundX MCP Integration Guide

GroundX supports the Model Context Protocol (MCP), allowing compatible AI agents and MCP clients to search GroundX-managed content through a standard tool interface.

MCP clients connect to the GroundX MCP endpoint and discover a search tool. The agent then calls that tool when it needs information from GroundX.

Endpoint

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

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

The endpoint is also available at:

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

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.

Search Scope

The MCP connection authenticates the client, but it does not automatically tell GroundX which bucket or documents to search.

The search scope must be provided to the search tool when the agent calls it.

GroundX supports two search scope forms:

• id: a GroundX bucket, group, or document ID
• documentIds: a list of specific GroundX document IDs

Exactly one of id or documentIds should be provided in each search tool call.

How the Agent Gets the Search Scope

There are three common ways to provide the search scope.

Option 1: User provides the scope in the prompt

The user can tell the agent which bucket or documents to search.

Example user prompt:

Search bucket 31 for the termination clause.

The MCP client can then call the GroundX search tool with:

1
{
2
  "id": "31",
3
  "query": "termination clause"
4
}

Option 2: Your application provides the scope

If your application already knows the bucket ID or document IDs, it should include that context in the agent instructions or tool-call workflow.

For example, your application might know that the current workspace maps to bucket 31. In that case, instruct the agent to use that bucket when calling GroundX search.

Example instruction to the agent:

When using the GroundX search tool, use id "31" unless the user specifies a different scope.

Option 3: Your MCP server binds a default scope

In some deployments, especially on-prem or customer-specific deployments, the MCP server can be configured with a default GroundX bucket or document set.

In that setup, the client only connects to the MCP server, and the server injects the configured search scope internally.

This is useful when every query should be limited to one customer, workspace, bucket, or document collection.

Available Tool

GroundX currently exposes one MCP tool:

search

The search tool retrieves relevant content from GroundX-managed documents.

The tool schema is exposed through MCP tool discovery. Compatible MCP clients should discover the tool and its parameters automatically.

Tool Arguments

The search tool accepts the following common arguments:

Example: Search by Bucket, Group, or Document ID

When searching a GroundX scope, provide id:

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

This is equivalent to searching within the GroundX scope identified by 31.

Example: Search Specific Documents

When searching specific documents, provide documentIds:

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

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/api/v1/mcp",
3
  "headers": {
4
    "X-API-Key": "YOUR_API_KEY",
5
    "Accept": "application/json, text/event-stream"
6
  }
7
}

Notes

• The MCP connection authenticates the client; it does not automatically choose a bucket or document scope.
• Provide either id or documentIds when calling the search tool.
• Do not provide both id and documentIds in the same search call.
• If every MCP request should search the same customer or workspace, configure the MCP server with a default scope instead of relying on the agent to choose one.
• Include Accept: application/json, text/event-stream for HTTP-based MCP requests.