# 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`

**Project identifier**: The AI will use its own shell access to determine the project's git remote (e.g., `git remote get-url origin`). This identifier scopes conventions and memories and ensures consistency across machines. If the directory isn't a git repo, you may need to provide a unique identifier manually.

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