120 lines
3.7 KiB
Markdown
120 lines
3.7 KiB
Markdown
# OpenCode MCP Configuration
|
|
|
|
OpenCode (open-source alternative to Cursor/Claude) supports MCP servers. This guide shows how to connect it to your AI Skills API MCP server running on `helm`.
|
|
|
|
## Prerequisites
|
|
|
|
- AI Skills API stack running on `helm` (includes MCP server on port 3000)
|
|
- OpenCode installed on your local machine
|
|
|
|
## MCP Server Endpoint
|
|
|
|
Your MCP server is accessible at:
|
|
```
|
|
http://helm:3000
|
|
```
|
|
|
|
It exposes two endpoints:
|
|
- `GET /sse` - Server-Sent Events (for client connection)
|
|
- `POST /messages` - JSON-RPC messages
|
|
|
|
## OpenCode Configuration
|
|
|
|
OpenCode reads MCP server config from its settings. You need to add an MCP server with the SSE URL.
|
|
|
|
### Configuration JSON
|
|
|
|
Add this to your OpenCode MCP configuration (location varies by install):
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"skills": {
|
|
"url": "http://helm:3000"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Note**: Use `"url"` not `"command"` since the server is remote and uses SSE transport.
|
|
|
|
### Where to Put This
|
|
|
|
OpenCode typically reads MCP config from:
|
|
- `~/.config/opencode/mcp.json`
|
|
- or in the app settings UI (Preferences → MCP → Add Server → Manual)
|
|
|
|
If using a file, create/edit `~/.config/opencode/mcp.json`:
|
|
|
|
```bash
|
|
mkdir -p ~/.config/opencode
|
|
cat > ~/.config/opencode/mcp.json << 'EOF'
|
|
{
|
|
"mcpServers": {
|
|
"skills": {
|
|
"url": "http://helm:3000"
|
|
}
|
|
}
|
|
}
|
|
EOF
|
|
```
|
|
|
|
### Test Connection
|
|
|
|
1. Restart OpenCode (if running)
|
|
2. Open the MCP servers panel/tool
|
|
3. You should see "skills" server listed as connected
|
|
4. Available tools will include:
|
|
- `search_skills`
|
|
- `get_skill`
|
|
- `list_skills`
|
|
- `get_context`
|
|
- `get_conventions`
|
|
- `get_snippets`
|
|
- `get_memory`
|
|
- `add_memory`
|
|
- `create_skill`
|
|
|
|
**First session**: The AI will ask you for your project identifier (recommended: your git remote origin URL like `https://github.com/username/repo`). This ensures your project conventions and memories are consistent across machines. If you don't know your git remote, run `git remote get-url origin` in your project directory. If you need to initialize a git repo or set up AI Skills, search for the "Project Setup Guide" skill.
|
|
|
|
## Troubleshooting
|
|
|
|
### "Cannot connect to MCP server"
|
|
- Ensure the stack is up: `docker compose -f /path/to/ai-skills-api/docker-compose.yml ps`
|
|
- Check MCP service logs: `docker compose logs mcp`
|
|
- Verify `helm` resolves: `ping helm` or use IP address instead
|
|
- If using IP, change config to `"url": "http://192.168.x.x:3000"`
|
|
|
|
### "Connection refused" or timeout
|
|
- Ensure port 3000 is exposed: `netstat -tuln | grep 3000` on helm
|
|
- Check firewall: helm should accept connections on 3000 from your network
|
|
|
|
### Tools not appearing
|
|
- Wait 10-20 seconds after OpenCode starts for MCP connection to establish
|
|
- Check OpenCode logs for MCP connection errors
|
|
- Verify the skills service is healthy: `docker compose ps` (mcp should be "Up" and healthy)
|
|
|
|
## Using the Tools
|
|
|
|
Once connected, you can invoke MCP tools from OpenCode:
|
|
|
|
- `get_context(project="/home/user/myapp")` → fetches relevant skills/conventions
|
|
- `search_skills(query="docker compose")` → finds matching skills
|
|
- `create_skill(...)` → adds new skill to the database
|
|
- `add_memory(project, key, content)` → stores learnings
|
|
|
|
These calls happen over the network to `helm:3000` and the MCP server forwards requests to the Skills API (`helm:8675` internally).
|
|
|
|
## Security Note
|
|
|
|
The MCP server is exposed on your home network without authentication (relies on network trust). If you need auth, we can add a reverse proxy or API key layer.
|
|
|
|
## One-Line Setup Script
|
|
|
|
If you're setting up on a new machine, run this from the `agentic-templates` repo:
|
|
|
|
```bash
|
|
./setup-opencode-mcp.sh
|
|
```
|
|
|
|
It will detect your OpenCode config location and add the MCP server automatically.
|