OpenCode Integration

Configure OpenGround MCP server in OpenCode by modifying opencode.json

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

Automatic Installation (Recommended)

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:

macOS

~/.config/opencode/opencode.json

Linux

~/.config/opencode/opencode.json

Windows

%USERPROFILE%\.config\opencode\opencode.json

Typically:

C:\Users\YourUsername\.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:

Field	Value	Description
type	"local"	Indicates a local subprocess server
command	["openground-mcp"]	Command as an array (not a string)
enabled	true	Whether 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

Native 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

WSL

If OpenGround is in WSL but OpenCode runs on Windows:

1. Generate WSL Config

   In WSL:

   openground install-mcp --wsl
   
2. Copy to Windows

   Edit Windows config at:

   C:\Users\YourUsername\.config\opencode\opencode.json
   

   Add:

   {
     "mcp": {
       "openground": {
         "type": "local",
         "command": ["wsl.exe", "openground-mcp"],
         "enabled": true
       }
     }
   }
   
3. Restart OpenCode

   Quit and restart completely

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