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

Restart OpenCode (if running)
Open the MCP servers panel/tool
You should see "skills" server listed as connected
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:

./setup-opencode-mcp.sh

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

3.6 KiB Raw Permalink Blame History