Menu
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/fabioc-aloha/ChessCoach --skill mcp-developmentThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Based on SOC occupation classification
Showing SKILL.md
| type | skill |
| lifecycle | stable |
| inheritance | inheritable |
| name | mcp-development |
| description | **Domain**: AI Infrastructure |
| tier | standard |
| applyTo | **/*mcp*,**/mcp.json,**/*model-context-protocol* |
| user-invokable | false |
| currency | 2026-04-22T00:00:00.000Z |
Domain: AI Infrastructure Inheritance: inheritable Version: 1.2.0 Last Updated: 2026-03-10
⚠️ Staleness Watch (EXTERNAL-API-REGISTRY.md): MCP spec and SDK are actively versioned. SDK moved from 1.0.0 → 1.27.1 with 3 security fixes: cross-client data leak in shared instances (GHSA-345p-7cg4-v4c7), ReDoS (v1.25.2), command injection prevention (v1.27.1). New SDK features: task types, elicitation streaming, OAuth discovery/caching, fetch transport, conformance testing, framework-agnostic server refactoring. Streamable HTTP replaced HTTP+SSE for remote servers (spec 2025-03-26). Check MCP Changelog and SDK Releases when advising on transport or SDK usage.
Complete guide to the Model Context Protocol (MCP)—an open standard for connecting AI assistants to external data sources and tools. Covers architecture, server development, client integration, and production deployment patterns.
Before MCP:
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Claude │ │ ChatGPT │ │ Copilot │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│Custom │ │Custom │ │Custom │
│Plugin A │ │Plugin A'│ │Plugin A"│
└─────────┘ └─────────┘ └─────────┘
(3 different implementations for same data source)
After MCP:
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Claude │ │ ChatGPT │ │ Copilot │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
└───────────────┼───────────────┘
▼
┌────────────┐
│ MCP Server │ (One implementation, many clients)
└────────────┘
| Concept | Description |
|---|---|
| Host | AI application (Claude Desktop, VS Code, etc.) |
| Client | MCP client within the host, manages server connections |
| Server | Provides tools, resources, and prompts via MCP |
| Communication layer (stdio, Streamable HTTP) |
┌─────────────────────────────────────────────────────────────┐
│ MCP Host │
│ (Claude Desktop, VS Code, IDE, Custom App) │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ MCP Client │ Manages protocol, routing, lifecycle │
│ └──────┬──────┘ │
│ │ │
│ Transport Layer (stdio / Streamable HTTP) │
│ │ │
└─────────┼───────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ MCP Server │
├─────────────────────────────────────────────────────────────┤
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ Tools │ │ Resources │ │ Prompts │ │
│ │ │ │ │ │ │ │
│ │ Functions │ │ Data/Files│ │ Templates │ │
│ │ AI calls │ │ AI reads │ │ AI uses │ │
│ └───────────┘ └───────────┘ └───────────┘ │
└─────────────────────────────────────────────────────────────┘
Functions the AI can execute:
// Tool definition
{
name: "search_issues",
description: "Search GitHub issues in a repository",
inputSchema: {
type: "object",
properties: {
repo: { type: "string", description: "owner/repo format" },
query: { type: "string", description: "Search query" },
state: {
type: "string",
enum: ["open", "closed", "all"],
default: "open"
}
},
required: ["repo", "query"]
}
}
Tool Design Principles:
Data the AI can read:
// Resource definition
{
uri: "github://repo/owner/repo-name/issues",
name: "Repository Issues",
description: "All issues in the repository",
mimeType: "application/json"
}
// Resource template (dynamic)
{
uriTemplate: "github://repo/{owner}/{repo}/issues/{id}",
name: "GitHub Issue",
description: "A specific GitHub issue",
mimeType: "application/json"
}
Resource Patterns:
Reusable prompt templates:
{
name: "code_review",
description: "Generate a code review for changes",
arguments: [
{
name: "diff",
description: "The code diff to review",
required: true
},
{
name: "focus",
description: "Areas to focus on (security, performance, style)",
required: false
}
]
}
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const server = new McpServer({
name: "my-mcp-server",
version: "1.0.0"
});
// Register a tool
server.tool(
"get_weather",
"Get current weather for a location",
{
location: {
type: "string",
description: "City name or coordinates"
}
},
async ({ location }) => {
const weather = await fetchWeather(location);
return {
content: [
{
type: "text",
text: JSON.stringify(weather, null, 2)
}
]
};
}
);
// Register a resource
server.resource(
"weather://current",
"Current weather data",
"application/json",
async () => ({
contents: [
{
uri: "weather://current",
mimeType: "application/json",
text: JSON.stringify(await getCurrentWeather())
}
]
})
);
// Start server
const transport = new StdioServerTransport();
await server.connect(transport);
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent
server = Server("my-mcp-server")
@server.list_tools()
async def list_tools():
return [
Tool(
name="get_weather",
description="Get current weather for a location",
inputSchema={
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City name"
}
},
"required": ["location"]
}
)
]
@server.call_tool()
async def call_tool(name: str, arguments: dict):
if name == "get_weather":
weather = await fetch_weather(arguments["location"])
return [TextContent(type="text", text=str(weather))]
raise ValueError(f"Unknown tool: {name}")
async def main():
async with stdio_server() as (read_stream, write_stream):
await server.run(read_stream, write_stream)
my-mcp-server/
├── package.json
├── tsconfig.json
├── src/
│ ├── index.ts # Entry point
│ ├── server.ts # Server setup
│ ├── tools/
│ │ ├── index.ts # Tool registry
│ │ ├── search.ts # Search tool
│ │ └── create.ts # Create tool
│ ├── resources/
│ │ ├── index.ts # Resource registry
│ │ └── data.ts # Data resources
│ └── utils/
│ ├── auth.ts # Authentication
│ └── cache.ts # Caching
└── tests/
└── tools.test.ts
Default for local servers:
// Claude Desktop config
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["/path/to/server/dist/index.js"],
"env": {
"API_KEY": "xxx"
}
}
}
}
Characteristics:
For remote/shared servers (replaces deprecated HTTP+SSE as of MCP spec 2025-03-26):
┌────────────┐ HTTPS ┌────────────┐
│ Client │ ◄─────────────────────► │ Server │
│ │ POST /mcp │ │
│ │ (streaming response) │ │
└────────────┘ └────────────┘
Characteristics:
⚠️ HTTP+SSE is deprecated. Old servers used
POST /message+GET /sse. If you encounter an HTTP+SSE server, it is using the legacy transport. Prefer Streamable HTTP for all new remote servers.
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
const transport = new StreamableHTTPServerTransport({ path: "/mcp" });
await server.connect(transport);
// Using MCP in VS Code extension
import { McpClient } from "@modelcontextprotocol/sdk/client/mcp.js";
const client = new McpClient({
name: "vscode-client",
version: "1.0.0"
});
// Connect to server
await client.connect(transport);
// List available tools
const { tools } = await client.listTools();
// Call a tool
const result = await client.callTool({
name: "search_issues",
arguments: { repo: "owner/repo", query: "bug" }
});
// Read a resource
const { contents } = await client.readResource({
uri: "github://repo/owner/repo/readme"
});
Per-User Config (Claude Desktop):
// ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
Workspace Config (VS Code):
// .vscode/mcp.json
{
"servers": {
"project-tools": {
"command": "node",
"args": ["./tools/mcp-server.js"]
}
}
}
// API key from environment
const apiKey = process.env.SERVICE_API_KEY;
if (!apiKey) {
throw new Error("SERVICE_API_KEY required");
}
// OAuth token refresh
async function getValidToken(): Promise<string> {
if (tokenExpired()) {
token = await refreshToken();
}
return token;
}
import { z } from "zod";
const SearchSchema = z.object({
query: z.string().min(1).max(500),
limit: z.number().int().min(1).max(100).default(10),
filters: z.object({
dateFrom: z.string().datetime().optional(),
dateTo: z.string().datetime().optional()
}).optional()
});
server.tool("search", "Search documents", SearchSchema, async (args) => {
const validated = SearchSchema.parse(args);
// Safe to use validated.query, validated.limit, etc.
});
import { RateLimiter } from "./utils/rate-limiter";
const limiter = new RateLimiter({
maxRequests: 100,
windowMs: 60 * 1000 // 1 minute
});
server.tool("expensive_operation", schema, async (args) => {
if (!limiter.tryAcquire()) {
return {
content: [{
type: "text",
text: "Rate limit exceeded. Please try again later."
}],
isError: true
};
}
// Proceed with operation
});
// Restrict file system access
const ALLOWED_PATHS = ["/data", "/tmp"];
function validatePath(requestedPath: string): boolean {
const resolved = path.resolve(requestedPath);
return ALLOWED_PATHS.some(allowed =>
resolved.startsWith(path.resolve(allowed))
);
}
// Restrict network access
const ALLOWED_HOSTS = ["api.example.com", "data.example.com"];
function validateUrl(url: string): boolean {
const parsed = new URL(url);
return ALLOWED_HOSTS.includes(parsed.hostname);
}
server.tool("risky_operation", schema, async (args) => {
try {
const result = await performOperation(args);
return {
content: [{ type: "text", text: JSON.stringify(result) }]
};
} catch (error) {
// Log for debugging
console.error("Operation failed:", error);
// Return user-friendly error
return {
content: [{
type: "text",
text: `Operation failed: ${getUserFriendlyMessage(error)}`
}],
isError: true
};
}
});
function getUserFriendlyMessage(error: unknown): string {
if (error instanceof AuthError) {
return "Authentication failed. Please check your credentials.";
}
if (error instanceof RateLimitError) {
return "Rate limit exceeded. Please try again in a few minutes.";
}
if (error instanceof ValidationError) {
return `Invalid input: ${error.message}`;
}
return "An unexpected error occurred. Please try again.";
}
import { Logger } from "./utils/logger";
const logger = new Logger("mcp-server");
server.tool("search", schema, async (args, context) => {
const requestId = context.requestId || crypto.randomUUID();
logger.info("Tool called", {
requestId,
tool: "search",
args: sanitizeForLogging(args)
});
const startTime = Date.now();
try {
const result = await performSearch(args);
logger.info("Tool completed", {
requestId,
tool: "search",
durationMs: Date.now() - startTime,
resultCount: result.items.length
});
return { content: [{ type: "text", text: JSON.stringify(result) }] };
} catch (error) {
logger.error("Tool failed", {
requestId,
tool: "search",
durationMs: Date.now() - startTime,
error: error.message
});
throw error;
}
});
import { LRUCache } from "lru-cache";
const cache = new LRUCache<string, any>({
max: 1000,
ttl: 5 * 60 * 1000 // 5 minutes
});
server.tool("fetch_data", schema, async ({ id }) => {
const cacheKey = `data:${id}`;
// Check cache
const cached = cache.get(cacheKey);
if (cached) {
return { content: [{ type: "text", text: JSON.stringify(cached) }] };
}
// Fetch fresh
const data = await fetchFromAPI(id);
cache.set(cacheKey, data);
return { content: [{ type: "text", text: JSON.stringify(data) }] };
});
import { describe, it, expect } from "vitest";
import { createTestServer } from "./test-utils";
describe("search tool", () => {
it("returns results for valid query", async () => {
const server = createTestServer();
const result = await server.callTool({
name: "search",
arguments: { query: "test", limit: 5 }
});
expect(result.content).toHaveLength(1);
expect(result.isError).toBeFalsy();
const data = JSON.parse(result.content[0].text);
expect(data.items).toHaveLength(5);
});
it("handles invalid input gracefully", async () => {
const server = createTestServer();
const result = await server.callTool({
name: "search",
arguments: { query: "", limit: -1 }
});
expect(result.isError).toBe(true);
expect(result.content[0].text).toContain("Invalid");
});
});
import { spawn } from "child_process";
import { McpClient } from "@modelcontextprotocol/sdk/client/mcp.js";
describe("MCP Server Integration", () => {
let serverProcess: ChildProcess;
let client: McpClient;
beforeAll(async () => {
// Start server process
serverProcess = spawn("node", ["dist/index.js"]);
// Connect client
client = new McpClient({ name: "test", version: "1.0.0" });
await client.connect(new StdioClientTransport(serverProcess));
});
afterAll(() => {
serverProcess.kill();
});
it("lists tools correctly", async () => {
const { tools } = await client.listTools();
expect(tools.map(t => t.name)).toContain("search");
});
});
| Server | Purpose | Install |
|---|---|---|
| filesystem | Local file access | @modelcontextprotocol/server-filesystem |
| github | GitHub API | @modelcontextprotocol/server-github |
| postgres | Database queries | @modelcontextprotocol/server-postgres |
| puppeteer | Web scraping | @modelcontextprotocol/server-puppeteer |
| memory | Persistent memory | @modelcontextprotocol/server-memory |
| Use Tool When | Use Resource When |
|---|---|
| Action with side effects | Read-only data access |
| Requires input parameters | Static or template URI |
| Returns computed result | Returns stored content |
| May fail or have errors | Generally stable data |
MCP tool calls are inherently synchronous — the tool returns a result and the interaction ends. This creates the same silent-handoff failure mode as extension commands: a write operation succeeds mechanically but the caller never learns that semantic review is needed.
Review every MCP tool handler against this table:
| # | Check | Pass | Fail | Action on Fail |
|---|---|---|---|---|
| 1 | Write tools gate on cross-project isolation — tools that write to AI-Memory or global scope enforce SK2 boundary | SK2 decision table rows evaluated before write | Direct write with no isolation check | Add SK2 gate; return structured warning if check fails |
| 2 | Read tools don't mutate — search/status tools have no side effects | Tool only reads files, returns data | Tool writes logs, creates files, or modifies state | Split into read tool + write tool; or explicitly document side effects |
| 3 | Error vs review distinction — tool result distinguishes "error" from "semantic review pending" | Result includes status: "review-required" when artifacts need LLM review | Only returns success or error; no handoff signal | Add semanticReviewRequired: true + reviewArtifact path to result schema |
| 4 | PII filter on outputs — tool results don't leak absolute paths with usernames or credentials | Paths are relative; no credentials in output | C:\Users\name\... paths or tokens in result JSON | Apply stripPII() before returning; use relative paths |
| 5 | Decision logging — write operations log to PE1 decision log | logPhase2Decision() called with tool name, action, rationale | Write completes with no audit trail | Integrate phase2-decision-log.cjs into tool handler |
| 6 | Input validation — tool validates all required fields before acting | Missing fields return descriptive error | Tool throws or returns empty result on bad input | Validate schema; return structured error with field requirements |
| 7 | Scope visibility — tool result includes scope metadata for caller's routing | Result includes scope: "project" or scope: "global" | Caller can't determine if result crosses project boundary | Add scope field to result schema |
| 8 | Backup before overwrite — tools that modify existing files preserve the original | .backup.md created before overwrite; path included in result | Original content lost on write | Create backup; include backupPath in result |
Known findings in alex-cognitive-tools (v1.1.0):
alex_knowledge_save fails rows 1, 3, 5, 8 — writes directly to AI-Memory with no isolation check, no decision logging, no review signal, and no backup of existing content.alex_health_check passes (read-only, no mutations).alex_memory_search and alex_knowledge_search pass (read-only).alex_architecture_status passes (read-only).MCP Development skill — Building AI-accessible tools and data sources