mcp-integration（MCP 集成）

MCP Meta Skill

🚨 MANDATORY: Invoke docs-management First

STOP - Before providing ANY response about MCP (Model Context Protocol): 1. INVOKE docs-management skill 2. QUERY for the user's specific topic 3. BASE all responses EXCLUSIVELY on official documentation loaded Skipping this step results in outdated or incorrect information.

Verification Checkpoint

Before responding, verify:

• Did I invoke docs-management skill?
• Did official documentation load?
• Is my response based EXCLUSIVELY on official docs?

If ANY checkbox is unchecked, STOP and invoke docs-management first.

Overview

Central authority for Claude Code Model Context Protocol (MCP) integration. This skill uses 100% delegation to docs-management - it contains NO duplicated official documentation.

Architecture: Pure delegation with keyword registry. All official documentation is accessed via docs-management skill queries.

When to Use This Skill

Keywords: MCP, Model Context Protocol, MCP servers, MCP tools, MCP resources, MCP prompts, HTTP transport, SSE transport, stdio transport, MCP installation, MCP scopes, local scope, project scope, user scope,.mcp.json, plugin MCP servers, enterprise MCP, managed-mcp.json, OAuth authentication, MCP resources, @ mentions, mcp__server__prompt, MCP output limits, MAX_MCP_OUTPUT_TOKENS, claude mcp serve

Use this skill when:

• Installing or configuring MCP servers
• Understanding MCP transport types (HTTP, SSE, stdio)
• Managing MCP server scopes (local, project, user)
• Working with plugin-provided MCP servers
• Setting up enterprise MCP configurations
• Using MCP resources with @ mentions
• Executing MCP prompts as slash commands
• Authenticating with remote MCP servers (OAuth)
• Configuring environment variable expansion in.mcp.json
• Using Claude Code as an MCP server
• Managing MCP output limits
• Troubleshooting MCP connection issues

Keyword Registry for docs-management Queries

Use these keywords when querying docs-management skill for official documentation:

Core Concepts

Installation and Transport

Server Management

Installation Scopes

Plugin Integration

Enterprise Configuration

Resources and Prompts

Authentication

Advanced Configuration

Tool Search & Auto Mode (v2.1.7+)

Behavior Change (v2.1.7): MCP tool search auto mode is now enabled by default with a 10% context threshold. Use auto:N syntax to configure custom thresholds (0-100%).

Behavior Change (v2.1.6): @-mention syntax for MCP servers was removed. Use /mcp enable <server> instead.

Security

Quick Decision Tree

What do you want to do?

1. Add a remote MCP server -> Query docs-management: "installing MCP servers", "HTTP transport MCP"
2. Add a local MCP server -> Query docs-management: "stdio transport MCP", "local stdio server"
3. Understand scopes -> Query docs-management: "MCP installation scopes", "scope precedence"
4. Share MCP with team -> Query docs-management: "project scope MCP", ".mcp.json file"
5. Use MCP across projects -> Query docs-management: "user scope MCP", "cross-project MCP"
6. Configure plugin MCP -> Query docs-management: "plugin-provided MCP servers"
7. Set up enterprise MCP -> Query docs-management: "enterprise MCP configuration", "managed-mcp.json"
8. Authenticate with OAuth -> Query docs-management: "MCP OAuth", "/mcp authentication"
9. Reference MCP resources -> Query docs-management: "MCP resources", "@ mentions MCP"
10. Use MCP prompts -> Query docs-management: "MCP prompts", "MCP skills"
11. Expose Claude as MCP server -> Query docs-management: "claude mcp serve"
12. Troubleshoot MCP issues -> Query docs-management: "MCP troubleshooting" + specific issue

Topic Coverage

Transport Types and Installation

• HTTP transport (recommended for remote servers)
• SSE transport (deprecated, use HTTP)
• Stdio transport (local processes)
• Windows-specific setup (cmd /c wrapper)
• Double dash (--) parameter explanation
• MCP_TIMEOUT environment variable

Server Management Commands

• claude mcp add (with transport flags)
• claude mcp list (show all servers)
• claude mcp get (server details)
• claude mcp remove (delete server)
• /mcp command (in-session status)
• claude mcp add-json (JSON configuration)
• claude mcp add-from-claude-desktop (import)
• claude mcp reset-project-choices (approval reset)

Scope Configuration

• Local scope (default, private to user/project)
• Project scope (.mcp.json, version controlled)
• User scope (cross-project, private)
• Scope precedence (local > project > user)
• --scope flag usage

Environment Variable Expansion

• ${VAR} syntax
• ${VAR:-default} syntax with defaults
• Supported expansion locations (command, args, env, url, headers)
• Missing variable handling

Plugin MCP Server Integration

• Plugin.mcp.json configuration
• Inline mcpServers in plugin.json
• CLAUDE_PLUGIN_ROOT variable
• Automatic lifecycle management
• Multiple transport type support

Enterprise MCP Management

• managed-mcp.json file locations (macOS, Windows, Linux)
• allowedMcpServers configuration
• deniedMcpServers configuration
• Allowlist/denylist precedence
• Enterprise scope precedence

MCP Resources System

• @ mention syntax for resources
• Resource path format (@server:protocol://path)
• Multiple resource references
• Fuzzy search in autocomplete
• Resource content types

MCP Prompts as Skills

• /mcp__servername__promptname format
• Executing prompts with arguments
• Dynamic discovery from servers
• Name normalization (spaces to underscores)

Authentication Mechanisms

• OAuth 2.0 support
• /mcp command for authentication
• Token storage and refresh
• Clear authentication option
• HTTP server authentication

Output Limits and Configuration

• Default 25,000 token limit
• Warning at 10,000 tokens
• MAX_MCP_OUTPUT_TOKENS configuration
• Use cases for higher limits

Claude Code as MCP Server

• claude mcp serve command
• Claude Desktop integration
• Configuration format
• Exposed tools (View, Edit, LS, etc.)
• Executable path configuration

Delegation Patterns

Standard Query Pattern

User asks: "How do I add an MCP server?"

1. Invoke docs-management skill
2. Use keywords: "installing MCP servers", "claude mcp add"
3. Load official documentation
4. Provide guidance based EXCLUSIVELY on official docs

Multi-Topic Query Pattern

User asks: "I want to share MCP servers with my team and authenticate with OAuth"

1. Invoke docs-management skill with multiple queries:
   - "project scope MCP", ".mcp.json file"
   - "MCP OAuth", "/mcp authentication"
2. Synthesize guidance from official documentation

Troubleshooting Pattern

User reports: "My MCP server won't connect on Windows"

1. Invoke docs-management skill
2. Use keywords: "Windows MCP servers", "cmd /c npx"
3. Check official docs for Windows-specific requirements
4. Guide user through Windows setup from official docs

Troubleshooting Quick Reference

Repository-Specific Notes

This repository uses MCP servers for:

• context7 MCP: Library documentation lookup
• firecrawl MCP: Web scraping and search
• microsoft-learn MCP: Microsoft/Azure documentation
• perplexity MCP: AI-powered search
• Ref MCP: Documentation reference lookup

MCP servers are configured in the project's settings and should follow the patterns documented in official Claude Code documentation.

Auditing MCP Configurations

This skill provides the validation criteria used by the mcp-auditor agent for formal audits.

CRITICAL: CLI-First Discovery (MANDATORY)

ALWAYS run claude mcp list FIRST before searching for configuration files. This is mandatory because:

1. File locations can change between Claude Code versions
2. User config is in ~/.claude.json (NOT ~/.claude/.mcp.json - this path does not exist)
3. The mcpServers key may be deep in the file (line 200+) - easy to miss with partial reads
4. CLI shows runtime state - files may not reflect what is actually running

# Step 1: Get authoritative list of configured servers
claude mcp list

# Step 2: Get details on specific server (shows scope and config)
claude mcp get <server-name>

Common Discovery Mistakes:

Audit Resources

Scoring Categories

Thresholds: 85+ = PASS, 70-84 = PASS WITH WARNINGS, <70 = FAIL

Related Agent

The mcp-auditor agent (Haiku model) performs formal audits using this skill:

• Auto-loads this skill via skills: mcp-integration
• Uses audit framework and docs-management for rules
• Generates structured audit reports
• Invoked by /audit-mcp command

External Technology Validation

When auditing MCP configurations that reference external technologies (scripts, packages, runtimes), the auditor MUST validate claims using MCP servers before flagging findings.

Technologies Requiring MCP Validation:

• .NET/C# scripts: Validate with microsoft-learn + perplexity
• Node.js/npm packages: Validate with context7 + perplexity
• Python scripts/packages: Validate with context7 + perplexity
• Shell scripts: Validate with perplexity
• Any version-specific claims: ALWAYS validate with perplexity

Validation Rule:

Never flag a technology usage as incorrect without first:

1. Querying appropriate MCP server(s) for current documentation
2. Verifying with perplexity for recent changes (especially.NET 10+)
3. Documenting MCP sources in the finding

Stale Data Warning:

• microsoft-learn can return cached/outdated documentation
• ALWAYS pair microsoft-learn with perplexity for version verification
• Trust perplexity for version numbers and recently-released features

References

Reference files:

• Audit Framework - Audit scoring and query guides
• Credential Patterns - Secure credential management patterns

Official Documentation (via docs-management skill):

• Primary: "mcp" documentation
• Related: "plugins", "hooks", "settings", "security"

Repository-Specific:

• MCP configuration: Project-level.mcp.json or local settings
• Skills configuration: .claude/settings.json

Version History

• v1.2.0 (2026-01-16): Tool Search & Auto Mode keywords (v2.1.6-v2.1.9)

- Added "Tool Search & Auto Mode (v2.1.7+)" keyword section - Auto mode default behavior change (10% threshold) - auto:N syntax for custom thresholds - Documented @-mention removal (v2.1.6) - use /mcp enable instead

• v1.1.0 (2025-12-25): Audit framework enhancement

- Added external technology validation guidance - Enhanced CLI-first discovery documentation - Improved scoring rubric for MCP audits

• v1.0.0 (2025-11-26): Initial release

- Pure delegation architecture - Comprehensive keyword registry - Quick decision tree - Topic coverage for all MCP features - Troubleshooting quick reference

Last Updated

Date: 2026-01-16 Model: claude-opus-4-5-20251101