---
name: mcp-diagnoser
description: Diagnose and fix MCP connectivity, authentication, and configuration failures in OpenCode
license: MIT
compatibility: opencode
metadata:
  audience: developers
  workflow: mcp-debugging
---

# MCP Diagnoser Skill

Troubleshoot MCP failures quickly, safely, and with clear remediation steps.

## What I Do

- Triage MCP statuses (`connected`, `failed`, `needs authentication`, `disabled`)
- Isolate root cause across config, auth, network, and local runtime dependencies
- Propose or apply minimal configuration fixes
- Re-validate with targeted checks and report final state

## When to Use Me

Use this when OpenCode MCP servers fail to connect or behave unexpectedly.

## Diagnostic Workflow

1. Capture baseline with `opencode mcp list`
2. Classify each failing server:
   - remote auth/headers/OAuth
   - endpoint or transport mismatch
   - local executable/dependency/path errors
3. Check required env vars and referenced config placeholders
4. Validate auth flow:
   - OAuth-capable servers: use `opencode mcp auth <name>`
   - token-header servers: verify token source and header wiring
5. Re-test with `opencode mcp list` and focused debug commands
6. Return root cause, concrete fix, and follow-up hardening suggestions

## Guardrails

- Never print secrets in full; always redact token values
- Never change unrelated MCP entries while fixing one server
- Prefer smallest viable fix before proposing larger rewrites