Custom Agent Integration

Integrate OpenGround with any MCP-compatible client using manual configuration.

Overview

OpenGround implements the Model Context Protocol (MCP) standard, making it compatible with any MCP client. This guide covers manual configuration for clients not covered by the automatic installers.

Prerequisites

Install OpenGround

pip install openground

Verify MCP Server

Test the server runs:

openground-mcp

Press Ctrl+C to exit

Add Documentation

Index at least one library:

openground add fastapi --source https://github.com/tiangolo/fastapi.git --docs-path docs -y

Generate Configuration

OpenGround provides a configuration generator:

openground install-mcp

Example Output

------------------ MCP Configuration ------------------

{
  "mcpServers": {
    "openground": {
      "command": "openground-mcp"
    }
  }
}

-------------------------------------------------------

Copy the JSON above into your MCP configuration file.
Tip: Run `openground install-mcp --claude-code`, `openground install-mcp --cursor`, 
or `openground install-mcp --opencode` to automatically install.

Standard MCP Configuration

Most MCP clients use a similar configuration structure:

{
  "mcpServers": {
    "openground": {
      "command": "openground-mcp"
    }
  }
}

Configuration Options

Field	Type	Description
`command`	string	Path to `openground-mcp` executable
`args`	array	Optional command-line arguments
`env`	object	Optional environment variables

Full Path Configuration

For reliability, use the absolute path to openground-mcp:

macOS/Linux
Windows

# Find the path
which openground-mcp
# Output: /usr/local/bin/openground-mcp

Configuration:

{
  "mcpServers": {
    "openground": {
      "command": "/usr/local/bin/openground-mcp"
    }
  }
}

# Find the path
where openground-mcp
# Output: C:\Python311\Scripts\openground-mcp.exe

Configuration:

{
  "mcpServers": {
    "openground": {
      "command": "C:\\Python311\\Scripts\\openground-mcp.exe"
    }
  }
}

Note: Escape backslashes in JSON (\\)

Platform-Specific Configuration

Windows Subsystem for Linux (WSL)

If your client runs on Windows but OpenGround is in WSL:

# In WSL, generate WSL config
openground install-mcp --wsl

Output:

{
  "mcpServers": {
    "openground": {
      "command": "wsl.exe",
      "args": ["openground-mcp"]
    }
  }
}

Virtual Environments

If OpenGround is in a virtual environment:

{
  "mcpServers": {
    "openground": {
      "command": "/path/to/venv/bin/openground-mcp"
    }
  }
}

Custom OpenGround Config

Use a non-default OpenGround configuration:

{
  "mcpServers": {
    "openground": {
      "command": "openground-mcp",
      "env": {
        "OPENGROUND_CONFIG": "/custom/path/config.json"
      }
    }
  }
}

MCP Tools Available

OpenGround exposes three tools through MCP:

1. list_libraries_tool

List available documentation libraries and versions. Input: None Output:

{
  "react": ["latest"],
  "fastapi": ["latest", "v0.109.0"],
  "django": ["latest", "v5.0"]
}

2. search_documents_tool

Search documentation using hybrid semantic + BM25 retrieval. Input:

query (string): Search query
library_name (string): Library to search
version (string): Library version

Output: Markdown with search results, including:

Relevant text chunks
Relevance scores
Source URLs
Hints for fetching full content

3. get_full_content_tool

Retrieve complete page content. Input:

url (string): Page URL from search results
version (string): Library version

Output: Full page content in markdown

Client-Specific Configurations

Generic MCP Client

For standard MCP clients:

{
  "mcpServers": {
    "openground": {
      "command": "openground-mcp",
      "transport": "stdio"
    }
  }
}

Zed Editor

Configuration for Zed’s MCP support:

{
  "language_servers": {
    "openground": {
      "command": "openground-mcp",
      "transport": "stdio"
    }
  }
}

VS Code (with MCP Extension)

If using an MCP extension for VS Code:

{
  "mcp.servers": {
    "openground": {
      "command": "openground-mcp"
    }
  }
}

Continue.dev

Configuration for Continue extension:

{
  "mcpServers": [
    {
      "name": "openground",
      "command": "openground-mcp"
    }
  ]
}

JetBrains IDEs (with MCP Plugin)

MCP support in JetBrains IDEs depends on third-party plugins. Configuration may vary.

Typical configuration:

<mcp-servers>
  <server name="openground" command="openground-mcp" />
</mcp-servers>

Advanced Configuration

Multiple Databases

Run separate OpenGround instances with different databases:

{
  "mcpServers": {
    "openground-work": {
      "command": "/work/venv/bin/openground-mcp",
      "env": {
        "OPENGROUND_CONFIG": "~/.openground-work/config.json"
      }
    },
    "openground-oss": {
      "command": "/oss/venv/bin/openground-mcp",
      "env": {
        "OPENGROUND_CONFIG": "~/.openground-oss/config.json"
      }
    }
  }
}

Read-Only Mode

OpenGround MCP server is read-only by design. It only exposes search tools, not modification tools.

Performance Tuning

Tune search performance via OpenGround config:

# Increase results
openground config set query.top_k 15

# Use faster embedding model
openground config set embeddings.model_name "sentence-transformers/all-MiniLM-L6-v2"

# Use fastembed backend for speed
openground config set embeddings.embedding_backend "fastembed"

Debugging

Test Server Manually

Run the server directly:

openground-mcp

The server listens on stdin/stdout. You should see no output (it’s waiting for JSON-RPC messages). Press Ctrl+C to exit.

Check PATH

Verify openground-mcp is in PATH:

macOS/Linux
Windows

which openground-mcp
echo $PATH

where openground-mcp
echo $env:PATH

Enable Logging

OpenGround MCP server logs to stderr:

# Redirect stderr to a log file for debugging
openground-mcp 2> /tmp/openground-mcp.log

In your client’s config:

{
  "mcpServers": {
    "openground": {
      "command": "sh",
      "args": ["-c", "openground-mcp 2>> /tmp/openground-mcp.log"]
    }
  }
}

Test with MCP Inspector

Use the MCP Inspector to test:

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Test OpenGround
mcp-inspector openground-mcp

Troubleshooting

Server Not Starting

Verify Installation

pip show openground
which openground-mcp

Test Server

openground-mcp
# Should start without errors

Check Python Environment

Ensure your client can access the same Python environment:

which python
python -c "import openground; print(openground.__file__)"

No Tools Available

If the client doesn’t see OpenGround tools:

Verify server is configured correctly
Restart the client completely
Check client logs for connection errors
Test with MCP Inspector

Search Returns No Results

Verify documentation is indexed:

# List libraries
openground list-libraries

# Check raw data
openground list-raw-libraries

# Add documentation if needed
openground add react --source https://github.com/facebook/react.git --docs-path docs -y

Permission Errors

Ensure execute permissions:

# macOS/Linux
chmod +x $(which openground-mcp)

# Windows: Usually not needed

Example: Writing a Custom Client

If you’re building a custom MCP client:

import subprocess
import json

# Start the server
process = subprocess.Popen(
    ["openground-mcp"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    text=True
)

# Send JSON-RPC request
request = {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
        "name": "list_libraries_tool",
        "arguments": {}
    },
    "id": 1
}

process.stdin.write(json.dumps(request) + "\n")
process.stdin.flush()

# Read response
response = process.stdout.readline()
print(json.loads(response))

See the MCP specification for complete protocol details.

Next Steps

MCP Overview

Learn more about MCP architecture

Add Libraries

Index more documentation

Configure Search

Customize embedding models and retrieval

API Reference

Detailed tool specifications

Get Started

Core Concepts

Adding Documentation

AI Agent Integration

Usage

Advanced

​Custom Agent Integration

​Overview

​Prerequisites

​Generate Configuration

​Standard MCP Configuration

​Configuration Options

​Full Path Configuration

​Platform-Specific Configuration

​Windows Subsystem for Linux (WSL)

​Virtual Environments

​Custom OpenGround Config

​MCP Tools Available

​1. list_libraries_tool

​2. search_documents_tool

​3. get_full_content_tool

​Client-Specific Configurations

​Generic MCP Client

​Zed Editor

​VS Code (with MCP Extension)

​Continue.dev

​JetBrains IDEs (with MCP Plugin)

​Advanced Configuration

​Multiple Databases

​Read-Only Mode

​Performance Tuning

​Debugging

​Test Server Manually

​Check PATH

​Enable Logging

​Test with MCP Inspector

​Troubleshooting

​Server Not Starting

​No Tools Available

​Search Returns No Results

​Permission Errors

​Example: Writing a Custom Client

​Next Steps

MCP Overview

Add Libraries

Configure Search

API Reference

Custom Agent Integration

Overview

Prerequisites

Generate Configuration

Standard MCP Configuration

Configuration Options

Full Path Configuration

Platform-Specific Configuration

Windows Subsystem for Linux (WSL)

Virtual Environments

Custom OpenGround Config

MCP Tools Available

1. list_libraries_tool

2. search_documents_tool

3. get_full_content_tool

Client-Specific Configurations

Generic MCP Client

Zed Editor

VS Code (with MCP Extension)

Continue.dev

JetBrains IDEs (with MCP Plugin)

Advanced Configuration

Multiple Databases

Read-Only Mode

Performance Tuning

Debugging

Test Server Manually

Check PATH

Enable Logging

Test with MCP Inspector

Troubleshooting

Server Not Starting

No Tools Available

Search Returns No Results

Permission Errors

Example: Writing a Custom Client

Next Steps