ai-skills-api/OPENCODE-MCP.md

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):

{
  "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:

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

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:

./setup-opencode-mcp.sh

It will detect your OpenCode config location and add the MCP server automatically.