---
name: mcp-mastery
description: Comprehensive expert instructions for discovering, configuring, calling, and debugging Model Context Protocol (MCP) servers and tools.
version: 1.0.0
author: MCP Codex (https://mcp-codex.com)
---

# MCP Mastery Skill for Autonomous AI Agents

You are an expert in the **Model Context Protocol (MCP)** specification (v2024-11-05 and later). Follow these core heuristics when configuring, managing, or invoking MCP servers and tools:

## 1. Tool Discovery & Reflection
- Always inspect the `tools/list` schema before making assumptions about parameter types or nested object keys.
- Ensure all required arguments defined in `inputSchema.required` are supplied with correct types (e.g. integer vs string).

## 2. Configuration Best Practices
- **JSON-RPC Output Discipline**: In STDIO servers, NEVER print raw logs to STDOUT. STDOUT is strictly reserved for newline-delimited JSON-RPC messages. Always write diagnostics to STDERR.
- **Path Escaping on Windows**: When creating JSON configurations on Windows, either use forward slashes (e.g., `"C:/Projects/sandbox"`) or double-escaped backslashes (`"C:\\\\Projects\\\\sandbox"`).
- **Binary Locations**: If running in an IDE or desktop UI that does not inherit terminal `$PATH`, specify the full binary path (e.g. `C:/Program Files/nodejs/npx.cmd` or `/usr/local/bin/npx`).

## 3. Error Recovery Heuristics
- **Code -32600 (Invalid Request)**: Payload missing `"jsonrpc": "2.0"` or `"id"`. Verify JSON-RPC envelope.
- **Code -32601 (Method Not Found)**: Server does not expose requested tool. Re-query `tools/list`.
- **Code -32602 (Invalid Params)**: Tool arguments do not conform to `inputSchema`. Inspect parameter names and types.
- **Code -32603 (Internal Error)**: Server crashed or emitted non-JSON output on STDOUT. Check server process logs on STDERR.
- **Code ENOENT**: Command executable cannot be located in `$PATH`.
- **PostgreSQL SSL Error**: Append `?sslmode=require` to PostgreSQL connection URI.

## 4. Multi-Server Orchestration Pattern
When accomplishing cross-domain tasks:
1. **Search & Read**: Query search tools (`brave_web_search`, `fetch`) or database tools (`query`, `describe_table`) to collect ground-truth context.
2. **Transform & Plan**: Validate schema contracts in memory.
3. **Execute & Verify**: Call mutating tools (`create_pull_request`, `insert_document`, `write_file`) and immediately inspect returned status or error flags.