Individual skill

diagnosing-mcp

Use to diagnose and fix ZCode MCP (Model Context Protocol) server configuration problems in the ZCode client. Applies when an MCP server will not connect, its tools (mcp__server__tool) do not appear, it shows as disabled or failed, connections time out, a command cannot be found, template variables are not expanded, or a server defined in a configuration file has no effect. Provides configuration locations, how to inspect status in Settings, common pitfalls, and a step-by-step localization and repair workflow.

GLM/skills/diagnosing-mcp/SKILL.md

Read pinned source

Source commit a2d33761e49b98f6ec1b48f12143264eb9b4ff4f

What was checked

Matches the observed repository HEAD: Yes
Scanner rules are current: No
Repository scan complete: No
Skill scan complete: Yes
Observed behavior: Not checked yet
Last checked: Nov 10, 2026

These are observations at the recorded commit, not a guarantee of safety. Review the source before running it.

Install this skill

Choose an agent in your Stack or copy a command below. Commands fetch the pinned commit and copy only this skill directory. Existing destinations are refused. Copying a command does not install anything.

An install command is unavailable: current rules, complete repository and skill scans, an eligible behavior level and a permitted license are required.

Repository context

Repository stars (not skill ratings): 71,245
Repository last updated: Nov 10, 2026
License: CC0-1.0

Observed agent integration: No specific integration evidence. Standard SKILL.md installation does not imply verified compatibility.

ai Repository topic
anthropic Repository topic
chatbot Repository topic
chatgpt Repository topic
claude Repository topic
claude-code Repository topic
codex Repository topic
gemini Repository topic
generative-ai Repository topic
google Repository topic
engineering Derived category

Files and excerpt

File metadata and permitted, redacted excerpts come from the recorded scan. Source links are pinned to that commit.

Browse files

SKILL.mdcore · 11,354 bytes

Read excerpt


# Diagnosing MCP Configuration

Goal: reduce any MCP problem to a single concrete file-field edit. A person inspects status from the client; an agent reads and edits the configuration files directly.

> Key points that are often misunderstood: the user configuration file is `~/.zcode/cli/config.json`; `.agents/mcp.json` is a **compatibility fallback** (read only when the same scope's `.zcode` has no MCP servers); and in the desktop client, MCP status and repair live under **Settings → MCP**.

## 1. Configuration locations and precedence

| Scope | File | Field |
|---|---|---|
| User | `~/.zcode/cli/config.json` | `mcp.servers` |
| User (fallback) | `~/.agents/mcp.json` | `mcpServers` (used only if `~/.zcode/cli/config.json` has no MCP servers) |
| Workspace | `<repo>/.zcode/config.json` or `<repo>/zcode.json` (every directory from the repository root down to the working directory is read) | `mcp.servers` |
| Workspace (fallback) | `<repo>/.agents/mcp.json` | `mcpServers` (used only if the workspace `.zcode` has no MCP servers) |