# MCP Troubleshooting

> Diagnose and fix MCP configuration/runtime issues across supported integrations using agents CLI checks.

- Skill: `bilal140202/mcp-troubleshooting` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bilal140202/mcp-troubleshooting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bilal140202/mcp-troubleshooting/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Bilal140202 (https://skillmd.com/u/bilal140202)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/bilal140202/mcp-troubleshooting

---


When MCP servers are failing or not visible:

1. Run `agents status --fast` to inspect configured vs enabled integrations.
2. Run `agents mcp test` for schema/config validation.
3. Run `agents mcp test --runtime` to check integration CLI/runtime connectivity.
4. Run `agents doctor` for environment and binary diagnostics.
5. Apply the smallest safe fix, then run `agents sync` and verify with `agents sync --check`.

Troubleshooting priorities:
- Missing binaries or PATH issues.
- Invalid server names/transport fields.
- Missing required environment variables or secrets.
- Target mismatch (server not routed to expected integration).