╔═══════════════════════════════════════════════════════════════════════════╗ ║ ║ ║ OPENCODE MCP SETUP - QUICK REFERENCE ║ ║ ║ ║ CLOUDFLARE INFRASTRUCTURE PROJECT ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════════════╝ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1. FILES CREATED ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📄 opencode.jsonc • Main OpenCode configuration file • 14 MCP servers defined (4 enabled, 10 optional) • Per-agent tool configuration • Environment variable management 📄 AGENTS.md • 3 custom agents documented • Project structure explained • Global rules and best practices • MCP quick reference guide 📄 MCP_GUIDE.md • Detailed guide for all 14 MCPs • Setup instructions per MCP • Usage examples • Troubleshooting section ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 2. MCP SERVERS SUMMARY ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ALWAYS ENABLED (Essential): ✅ filesystem Type: Local (@modelcontextprotocol/server-filesystem) Purpose: File operations, directory exploration When: Examining project files ✅ git Type: Local (@modelcontextprotocol/server-git) Purpose: Version control, commit history When: Reviewing changes, understanding history ✅ github Type: Local (@modelcontextprotocol/server-github) Purpose: GitHub API, repos, PRs, issues Requires: GITHUB_TOKEN environment variable When: Searching implementations, managing PRs ✅ gh_grep Type: Remote (https://mcp.grep.app) Purpose: GitHub code search When: Finding examples and best practices ──────────────────────────────────────────────────────────────────────────── OPTIONAL - ENABLE AS NEEDED: ⚠️ postgres Type: Local (@modelcontextprotocol/server-postgres) Requires: DATABASE_URL Use: Database queries, schema exploration Enable: For data-engineer agent ⚠️ sqlite Type: Local (@modelcontextprotocol/server-sqlite) Use: Local data analysis Enable: For data-engineer agent ⚠️ docker Type: Local (@modelcontextprotocol/server-docker) Use: Container management Enable: When working with containers ⚠️ aws Type: Local (@modelcontextprotocol/server-aws) Requires: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION Use: AWS infrastructure Enable: For AWS deployments ⚠️ slack Type: Local (@modelcontextprotocol/server-slack) Requires: SLACK_BOT_TOKEN Use: Send notifications to Slack Enable: For automated alerts ⚠️ linear Type: Local (@modelcontextprotocol/server-linear) Requires: LINEAR_API_KEY Use: Create/manage Linear issues Enable: For issue tracking ⚠️ context7 Type: Remote (https://mcp.context7.com/mcp) Requires: CONTEXT7_API_KEY (optional) Use: Search documentation Enable: For compliance research ⚠️ googlemaps Type: Local (@modelcontextprotocol/server-google-maps) Requires: GOOGLE_MAPS_API_KEY Use: Map queries, geocoding Enable: For location-based features ⚠️ memory Type: Local (@modelcontextprotocol/server-memory) Use: Store/retrieve project knowledge Enable: For pattern recording ⚠️ web-scraper Type: Local (web-scraper-mcp) Use: Web scraping Enable: For data extraction ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3. ENVIRONMENT VARIABLES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ESSENTIAL: export GITHUB_TOKEN="ghp_your_github_personal_access_token" (Get from: https://github.com/settings/tokens) RECOMMENDED: export CONTEXT7_API_KEY="your_context7_api_key" (Optional - enables doc search, free tier available) OPTIONAL (as needed): export DATABASE_URL="postgresql://user:pass@localhost:5432/db" export AWS_ACCESS_KEY_ID="AKIA..." export AWS_SECRET_ACCESS_KEY="..." export AWS_REGION="us-east-1" export SLACK_BOT_TOKEN="xoxb-..." export LINEAR_API_KEY="lin_..." export GOOGLE_MAPS_API_KEY="..." ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4. CUSTOM AGENTS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ /agent cloudflare-ops ───────────────────── Purpose: Terraform and GitOps management Tools: filesystem, git, github, gh_grep Use: "I need to add DNS records" or "Update WAF rules" /agent security-audit ──────────────────── Purpose: Security and compliance reviews Tools: filesystem, git, github, gh_grep Use: "Check PCI-DSS compliance" or "Review WAF configuration" /agent data-engineer ─────────────────── Purpose: Database operations Tools: filesystem, git, postgres, sqlite Use: "Query user data" or "Analyze metrics" ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 5. GETTING STARTED ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ STEP 1: Set environment variables $ export GITHUB_TOKEN="ghp_..." $ export CONTEXT7_API_KEY="your_key" # optional STEP 2: Navigate to project $ cd /Users/sovereign/Desktop/CLOUDFLARE STEP 3: Start OpenCode $ opencode STEP 4: Inside OpenCode, initialize /init STEP 5: Start using agents /agent cloudflare-ops I need to implement HTTPS enforcement for all zones STEP 6: Check MCP status (anytime) /mcp list /mcp status github ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 6. COMMON WORKFLOWS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ WORKFLOW 1: Adding Infrastructure /agent cloudflare-ops I need to add a DNS record. Use gh_grep to find similar examples first. → OpenCode searches GitHub for patterns, shows examples, implements change WORKFLOW 2: Security Audit /agent security-audit Review the WAF rules and check against PCI-DSS requirements. → OpenCode examines config, searches compliance docs, creates report WORKFLOW 3: Database Query /agent data-engineer Query the analytics database for user counts by region. → OpenCode connects to postgres, runs query, formats results WORKFLOW 4: Finding Best Practices Use the gh_grep tool to find Cloudflare patterns on GitHub → OpenCode searches grep.app, returns code examples ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 7. IMPORTANT NOTES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✅ MCPs add to context usage - Keep heavy MCPs (github) disabled globally if context-limited - Enable them per-agent when needed ✅ Environment variables must be set BEFORE running opencode - OpenCode won't find them if exported after startup - Use .env file in project or shell profile ✅ Some MCPs require paid tiers - github: Free tier available - context7: Free tier available - context7 works without API key but with rate limits ✅ Always use version control - Commit opencode.jsonc, AGENTS.md to git - This helps team consistency ✅ Customize for your team - Edit AGENTS.md to add team-specific agents - Enable/disable MCPs based on team needs ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 8. TROUBLESHOOTING ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ MCP not loading? → Check: /mcp list → Verify: environment variables are set → Restart: exit and rerun opencode GitHub MCP not working? → Check: export GITHUB_TOKEN="ghp_..." → Verify: token has required scopes (repo, read:org) → Check: /mcp status github Context limit exceeded? → Disable heavy MCPs globally → Enable per-agent only → Use plan mode to reduce context usage ──────────────────────────────────────────────────────────────────────────── For complete details, see: • AGENTS.md - Agent documentation and rules • MCP_GUIDE.md - Complete MCP reference guide • opencode.jsonc - Configuration file (editable) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Updated: December 8, 2025 OpenCode Version: 1.0+ Status: Ready to use ✅