# MCP Sync

> Audit and sync MCP tool references in plugin files against actual MCP server configurations. Use when validating tool names, checking for stale MCP calls, syncing tool definitions after server changes, or phrases like 'sync MCP tools', 'validate tool references', 'check MCP schema'. Returns a structured diff report and optionally applies fixes.

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

---


# MCP Sync

Validate that MCP tool references in a plugin's commands, skills, and agents match the
tools actually exposed by the configured MCP servers.

## When to Use

- After adding, removing, or renaming an MCP server in `.mcp.json`
- After an MCP server package is updated (tools may have been added/removed/renamed)
- As a pre-flight check before committing plugin file changes
- When another agent needs to verify tool references are correct

## Procedure

### 1. Identify the plugin

Use the provided path argument, or list `plugins/` and ask the user.
Confirm that `<plugin-path>/.mcp.json` exists.

### 2. Build the source-of-truth tool inventory

Read `<plugin-path>/.mcp.json` to get the server names and packages.

For each server, discover its actual tools using `tool_search_tool_regex` with the
pattern `mcp_<server_name>` (replace hyphens with underscores in the server name).

Record each tool's full name and description. If a server is unavailable, mark it
`⚠ UNAVAILABLE` and skip — never guess tool names.

### 3. Scan plugin files for tool references

Search all `.md` files in the plugin's `commands/`, `skills/`, and `agents/` directories.

Match these patterns:
- Bare tool names: `kendo_component_assistant`, `browser-navigate`
- Qualified names: `server-name.tool_name`
- MCP-prefixed: `mcp__server-name__tool_name`
- `#tool:` syntax
- Frontmatter `tools:` arrays
- Server name mentions in prose

### 4. Cross-reference and classify

Compare scanned references against the tool inventory:

| Status | Icon | Meaning |
|--------|------|---------|
| Valid | ✅ | Reference matches an actual tool |
| Stale | ❌ | No matching tool found |
| Renamed | 🔄 | Close match to an actual tool (fuzzy) |
| Undocumented | ➕ | Actual tool not referenced in any file |
| Inconsistent | ⚠️ | Same tool named differently across files |
| Server missing | 🔌 | References a server not in `.mcp.json` |

### 5. Produce the report

Output a markdown report grouped by file, with a summary table at the end:

```
## MCP Sync Report: <plugin-name>

### <file-path>
  ✅ tool_name — matches <server> tool
  ❌ old_tool_name — no match
  🔄 old_tool_name → new_tool_name (likely rename)

### Summary
  ✅ Valid: N    ❌ Stale: N    🔄 Renames: N
  ➕ Undocumented: N    ⚠️ Inconsistent: N
```

### 6. Apply fixes (if requested)

When invoked by the `mcp-sync` agent or when the user confirms, update tool names
in the affected files:
- Replace stale names with correct names
- Standardize naming to match the plugin's existing convention
- Add undocumented tools to the most relevant file section
- Preserve all surrounding prose and formatting

### 7. Verify

Re-run scan after fixes to confirm all references resolve to ✅.