Custom Agent Integration

Configure OpenGround MCP server for other AI agents and custom clients

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

1. Install OpenGround

   pip install openground
   
2. Verify MCP Server

   Test the server runs:

   openground-mcp
   

   Press Ctrl+C to exit

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

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

Configuration:

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

Windows

# 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

which openground-mcp
echo $PATH

Windows

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

1. Verify Installation

   pip show openground
   which openground-mcp
   
2. Test Server

   openground-mcp
   # Should start without errors
   
3. 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:

1. Verify server is configured correctly
2. Restart the client completely
3. Check client logs for connection errors
4. 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