Skip to main content

​
OpenCode Integration

Integrate OpenGround with OpenCode to search documentation during your AI-assisted development sessions.

​
Prerequisites

1

Install OpenGround

pip install openground
2

Add Documentation

Index at least one library:
openground add fastapi --source https://github.com/tiangolo/fastapi.git --docs-path docs -y
3

Install OpenCode

Download from opencode.sh

​
Installation

OpenGround provides an automatic installer for OpenCode: 
openground install-mcp --opencode
This command:
  1. Locates your OpenCode config at ~/.config/opencode/opencode.json
  2. Creates a timestamped backup of existing config
  3. Safely merges the OpenGround MCP server configuration
  4. Validates JSON before writing
Success! You should see: “Successfully installed openground to OpenCode!”

​
Configuration Structure

The installer adds this configuration to opencode.json: 
{
  "mcp": {
    "openground": {
      "type": "local",
      "command": ["openground-mcp"],
      "enabled": true
    }
  }
}

​
Configuration File Location

OpenCode stores its configuration at: 
~/.config/opencode/opencode.json

​
Manual Installation

If you prefer to manually edit the configuration:
1

Generate Configuration

openground install-mcp
This displays the JSON without modifying files
2

Locate OpenCode Config

Navigate to ~/.config/opencode/opencode.json
3

Edit Configuration

Add the OpenGround server to the mcp section:
{
  "mcp": {
    "openground": {
      "type": "local",
      "command": ["openground-mcp"],
      "enabled": true
    }
  }
}
If you have existing MCP servers, add OpenGround alongside them:
{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["some-other-server"],
      "enabled": true
    },
    "openground": {
      "type": "local",
      "command": ["openground-mcp"],
      "enabled": true
    }
  }
}
4

Validate JSON

Ensure proper syntax (no trailing commas, quotes, etc.)

​
Configuration Details

​
OpenCode MCP Schema

OpenCode’s MCP configuration differs slightly from other clients:
FieldValueDescription
type"local"Indicates a local subprocess server
command["openground-mcp"]Command as an array (not a string)
enabledtrueWhether the server is active

​
Command Resolution

The installer uses the full path to openground-mcp if found in PATH: 
{
  "mcp": {
    "openground": {
      "type": "local",
      "command": ["/usr/local/bin/openground-mcp"],
      "enabled": true
    }
  }
}

​
Transport Protocol

OpenGround uses stdio (standard input/output):
  • OpenCode spawns openground-mcp as a subprocess
  • Communication via stdin/stdout
  • No network ports required

​
Backup Files

The installer creates timestamped backups before making changes: 
~/.config/opencode/opencode.json.backup.20240228_153045
Restore from backup if needed: 
cp ~/.config/opencode/opencode.json.backup.YYYYMMDD_HHMMSS ~/.config/opencode/opencode.json

​
Verification

1

Restart OpenCode

Completely quit and restart OpenCode
2

Check MCP Status

In OpenCode settings or console, verify OpenGround MCP is connected
3

Test Tools

Ask OpenCode: “What documentation is available in openground?”OpenCode should call list_libraries_tool and display your indexed libraries

​
Using OpenGround in OpenCode

​
Automatic Tool Invocation

OpenCode will automatically use OpenGround when appropriate: 
You: How do I create a FastAPI route with path parameters?

OpenCode: Let me check the FastAPI documentation...
[Calls mcp__openground__search_documents_tool]

According to the official FastAPI docs:
...

​
Explicit Documentation Searches

Request specific documentation searches: 
You: Search openground for React context API examples

OpenCode: [Searches React documentation]

​
Combining Code and Docs

OpenCode can analyze your code alongside documentation: 
You: Is this the correct way to use Django model validators?
[paste code]

OpenCode: [Analyzes code + searches Django docs for validator patterns]

​
Platform-Specific Configuration

​
macOS

No additional configuration needed. Works out of the box.

​
Linux

Ensure pip’s bin directory is in PATH: 
# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

# Reload
source ~/.bashrc
Verify: 
which openground-mcp
# Should output: /home/username/.local/bin/openground-mcp

​
Windows

Add Python Scripts to PATH:
# Check availability
where openground-mcp
If not found:
  1. Open System Properties → Environment Variables
  2. Add to PATH: 
    C:\Users\YourUsername\AppData\Local\Programs\Python\Python311\Scripts
  3. Restart terminal/OpenCode
Run installer:
openground install-mcp --opencode

​
Advanced Configuration

​
Disable OpenGround Temporarily

Set enabled to false without removing the configuration: 
{
  "mcp": {
    "openground": {
      "type": "local",
      "command": ["openground-mcp"],
      "enabled": false
    }
  }
}

​
Use Specific Virtual Environment

Point to a specific Python environment: 
{
  "mcp": {
    "openground": {
      "type": "local",
      "command": ["/path/to/venv/bin/openground-mcp"],
      "enabled": true
    }
  }
}

​
Environment Variables

Pass custom environment variables: 
{
  "mcp": {
    "openground": {
      "type": "local",
      "command": ["openground-mcp"],
      "enabled": true,
      "env": {
        "OPENGROUND_CONFIG": "/custom/path/config.json"
      }
    }
  }
}

​
Multiple OpenGround Instances

Run separate instances with different databases: 
{
  "mcp": {
    "openground-work": {
      "type": "local",
      "command": ["/work/venv/bin/openground-mcp"],
      "enabled": true,
      "env": {
        "OPENGROUND_CONFIG": "~/.openground-work/config.json"
      }
    },
    "openground-oss": {
      "type": "local",
      "command": ["/oss/venv/bin/openground-mcp"],
      "enabled": true,
      "env": {
        "OPENGROUND_CONFIG": "~/.openground-oss/config.json"
      }
    }
  }
}

​
Troubleshooting

​
Configuration Not Applied

1

Verify File Location

Confirm opencode.json exists at ~/.config/opencode/
2

Check JSON Syntax

Validate with:
python -m json.tool ~/.config/opencode/opencode.json
3

Restart OpenCode Completely

Quit entirely (not just close window), then restart

​
Invalid JSON Error

If OpenCode reports JSON errors: 
# Restore from backup
cp ~/.config/opencode/opencode.json.backup.YYYYMMDD_HHMMSS ~/.config/opencode/opencode.json

# Re-run installer
openground install-mcp --opencode

​
Permission Denied

Fix file permissions: 
# Linux/macOS
chmod 644 ~/.config/opencode/opencode.json

# Windows: Right-click → Properties → Security → Edit

​
Command Not Found

1

Verify Installation

which openground-mcp  # macOS/Linux
where openground-mcp  # Windows
2

Use Full Path

Edit opencode.json with full path:
{
  "mcp": {
    "openground": {
      "type": "local",
      "command": ["/full/path/to/openground-mcp"],
      "enabled": true
    }
  }
}
3

Check PATH

Ensure Python bin/Scripts directory is in PATH

​
MCP Server Not Starting

Debug the server: 
# Test server manually
openground-mcp
# Should start without errors (Ctrl+C to exit)

# Check OpenCode logs for error messages

​
No Search Results

Verify documentation: 
# List libraries
openground list-libraries

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

​
Updating Configuration

Re-run the installer to update: 
openground install-mcp --opencode
The installer:
  1. Creates a new timestamped backup
  2. Preserves other MCP servers
  3. Updates only OpenGround configuration

​
Next Steps

Add Libraries

Index more documentation sources

Configure Search

Customize embedding models and retrieval

MCP Overview

Learn about MCP architecture

Custom Agents

Use with other MCP clients