2.MCP

👉 #AI #LLM #Agent #Coding #DevTools

I. MCP (Model Context Protocol)

📅 2026-04-28 CDT; Claude Opus 4.6 📎 MCP Official Specification 📎 MCP GitHub Organization 📎 MCP Python SDK 📎 MCP TypeScript SDK 📎 FastMCP (Python) 📎 FastMCP (TypeScript) 📎 MCP Official Registry 📎 WorkOS MCP Features Guide

1. Overview

1.1. Definition & Why

MCP (Model Context Protocol) is an open standard that gives AI applications a uniform way to connect to external tools, data sources, and services.
Open-sourced by Anthropic in November 2024; donated to the Linux Foundation's Agentic AI Foundation (AAIF) in December 2025; jointly governed by Anthropic, OpenAI, Google, Microsoft, AWS, and Block.
Core metaphor: the "USB-C port" of the AI world — write one MCP Server and any MCP-compatible Client (Claude, ChatGPT, Cursor, Kiro, VS Code, etc.) can use it directly.
Pain solved: the N×M integration problem.
Without MCP: N AI applications × M external tools = N×M custom integrations
With MCP: N Clients + M Servers = N+M standardized implementations
Analogy: before USB, every device had its own connector; with USB, one connector serves all devices.
Technical essence: a stateful, session-based protocol over JSON-RPC 2.0 supporting bidirectional communication.
As of mid-2026: 97M+ monthly SDK downloads, 5,800+ Servers in the official Registry, 10,000+ public Servers.

1.2. Features & Use Cases

(1) Core Features

Feature	Description
Universal	One Server works for all MCP Clients — no need to develop separately for each platform
Three Primitives	Tools (actions), Resources (data), Prompts (templates) cover almost every integration need
Stateful Sessions	Persistent JSON-RPC connections; multi-turn interaction and context retention
Bidirectional	Server can also send requests to the Client (Sampling, Elicitation)
Transport Agnostic	Supports stdio (local) and Streamable HTTP (remote); custom transports allowed
Security First	OAuth 2.1 auth, tool-level permission control, input validation
Progressive Discovery	Client discovers Server capabilities at startup, calls on demand
Vendor Neutral	Linux Foundation governance — not controlled by any single company

(2) Typical Use Cases

Database queries: MCP Server connects to PostgreSQL/MySQL/DynamoDB; Agent queries via natural language.
Filesystem operations: read/write local or remote files; search code repos.
API integration: wrap REST/GraphQL APIs as MCP Tools that Agents can call directly.
Browser automation: control browsers via Playwright/Puppeteer MCP Servers.
DevOps toolchain: trigger CI/CD pipelines, query logs, monitor alerts.
Knowledge-base retrieval: connect to Confluence, Notion, internal wikis.
Cloud-service management: query and manage AWS/GCP/Azure resources.
Code analysis: integrate with static analysis, lint, test runners.

1.3. Competitors & Alternatives

Protocol/Approach	Sponsor	Position	Pros	Cons
MCP	Anthropic → AAIF	Agent ↔ Tool (vertical)	De-facto standard, 97M+ downloads, 10K+ Servers	Documentation has been criticized as immature
A2A (Agent-to-Agent)	Google → AAIF	Agent ↔ Agent (horizontal)	150+ org support, gRPC, signed agent cards	Newer (2025-04); ecosystem still building
ACP (Agent Communication)	Community	Agent-to-Agent comms	Community-driven, flexible	Low adoption; lacks big-vendor backing
Function Calling	OpenAI et al.	Single tool call	Simple, supported by all LLMs	Stateless; schema sent every request — token-wasteful
LangChain Tools	LangChain	Tools inside the Agent framework	Rich ecosystem, flexible	Framework-bound, not portable
Semantic Kernel Plugin	Microsoft	AI orchestration framework	Type-safe, enterprise-grade	Language-bound (C#/Python)
Agent Skills (SKILL.md)	Anthropic	Instruction bundles (how the Agent should do things)	Cross-platform, 20+ platforms	Focuses on instructions, not tool calls

Key distinctions:
MCP vs A2A: MCP is "vertical integration" (Agent ↔ Tool); A2A is "horizontal integration" (Agent ↔ Agent). Complementary, both now under AAIF.
MCP vs Function Calling: Function Calling is a single stateless invocation; MCP is a stateful session supporting discovery, multi-turn, and bidirectional comms.
MCP vs Agent Skills: Skills define "how to do" (workflow instructions); MCP provides "what can be done" (tools and data). See 4.Protocol/1.Skill.md §2.1(5).

2. Concept, Component, & Architecture

2.1. Key Concepts

(1) JSON-RPC 2.0 — the foundation

All MCP messages are JSON-RPC 2.0, UTF-8 encoded.
Three message types:
Request: has an id; expects a response.
Response: reply to a request; carries result or error.
Notification: no id; one-way message; no reply expected.
This is the base for understanding everything in MCP — Tools, Resources, Prompts are all JSON-RPC underneath.

(2) Three Primitives

The core MCP design is three primitives that cover all Agent ↔ external-system interactions:

Primitive	Controlled by	Direction	Analogy	Description
Tools	Model	Server → Client	Function / API endpoint	Actions the Agent can call (queries, writes, computation)
Resources	App / User	Server → Client	GET endpoint / file	Data the Agent can read (files, DB records)
Prompts	User	Server → Client	Template / slash command	Predefined interaction templates (workflows, forms)

Tools: invoked autonomously by the Model. Like Function Calling but stateful and discoverable.
Resources: loaded under control of the Application or User. Like REST GET — provides context data.
Prompts: explicitly triggered by the User. Like a Slash Command — provides a structured entry point.

(3) Capability Negotiation

Client and Server exchange supported capabilities at connection time via the initialize handshake.
Client declares: Sampling? Roots? Elicitation?
Server declares: Tools? Resources? Prompts? Logging?
This negotiation ensures both sides only use features the other supports — forward compatibility.

(4) Transport

MCP defines two standard transports, decoupling protocol logic from transport:

Transport	Best fit	Notes
stdio	Local process	Client spawns Server as a subprocess; communicates via stdin/stdout
Streamable HTTP	Remote deploy	HTTP POST + optional SSE; supports both stateless and stateful modes

stdio: simplest; the Client spawns the Server. Best for local IDE integrations (Kiro, Claude Desktop).
Streamable HTTP: introduced in the 2025-03-26 spec, replacing the older SSE-only transport. Supports OAuth 2.1; great for cloud deployment.
Deprecated: HTTP+SSE (old remote transport, replaced by Streamable HTTP).

(5) Lifecycle

sequenceDiagram
  participant C as Client
  participant S as Server

  C->>S: initialize (Client capabilities + protocol version)
  S-->>C: initialize response (Server capabilities + protocol version)
  C->>S: initialized notification (handshake complete)

  Note over C,S: Normal operations (Tools/Resources/Prompts)

  C->>S: ping (heartbeat — either side may initiate)
  S-->>C: pong

  C->>S: shutdown (graceful close)
  S-->>C: shutdown response

(6) Advanced Capabilities

Beyond the three primitives:

Capability	Direction	Description
Sampling	Server → Client	Server asks the Client's LLM to generate text (reverse call)
Elicitation	Server → Client	Server asks the Client to collect user input (forms, confirmations)
Roots	Client → Server	Client tells the Server which filesystem roots are accessible
Logging	Server → Client	Server sends structured logs to the Client
Completion	Client → Server	Client asks the Server for argument auto-completion suggestions
Pagination	Bidirectional	Page through large result sets

Sampling is one of MCP's most distinctive designs: it lets a Server reverse-call the Client's LLM, enabling "Agent inside the Agent" patterns.
Elicitation was added in the November 2025 spec: lets a Server request additional input from the user mid-tool-execution — interactive workflows.

2.2. Core Components

(1) MCP Host

The AI app the user directly interacts with (Claude Desktop, Kiro, Cursor, VS Code).
Manages one or more MCP Client instances.
Controls Client permissions and security policies.
Provides LLM inference capability (used by Sampling).

(2) MCP Client

Created by the Host; maintains a 1:1 stateful session with a single MCP Server.
Handles protocol negotiation, message routing, capability discovery.
A Host can manage many Clients, each connected to one Server.
Implements JSON-RPC message serialization/deserialization.

(3) MCP Server

Exposes Tools, Resources, Prompts to the Client.
Connects to actual external systems (DBs, APIs, file systems).
Can be a local process (stdio) or a remote service (Streamable HTTP).
Each Server focuses on a specific domain (GitHub Server, PostgreSQL Server, Filesystem Server).

(4) Tools

Server-exposed executable actions; the LLM autonomously decides when to call.
Each Tool has: name, description, inputSchema (JSON Schema).
The Agent uses description to decide when to call and inputSchema to construct arguments.
Examples: query_database, send_email, create_file, search_web.
Supports annotations: side-effect (readOnlyHint), idempotency (idempotentHint), etc.

(5) Resources

Server-exposed readable data; loaded under Application or User control.
Identified by URI (file:///path/to/doc.md, postgres://db/table).
Supports static resource lists and dynamic templates (URI Template).
Content types: text (UTF-8) or blob (Base64-encoded binary).
Supports change subscriptions (Resource Subscription).

(6) Prompts

Server-exposed predefined interaction templates; explicitly chosen by the User.
Like Slash Commands: user picks a Prompt in the UI, fills in arguments, and the system generates structured messages.
Supports dynamic arguments and multi-step workflows.
Best for: code-review templates, data-analysis flows, report generation.

2.3. Architecture & Design

(1) Overall Architecture

graph TB
  subgraph Host["MCP Host (Claude Desktop / Kiro / Cursor / VS Code)"]
    LLM["LLM Engine"]
    CA["MCP Client A"]
    CB["MCP Client B"]
    CC["MCP Client C"]
  end

  subgraph SA["MCP Server A (GitHub)"]
    TA["Tools / Resources"]
  end
  subgraph SB["MCP Server B (Postgres)"]
    TB["Tools / Resources"]
  end
  subgraph SC["MCP Server C (Files)"]
    TC["Tools / Resources"]
  end

  CA -->|stdio| SA
  CB -->|HTTP| SB
  CC -->|stdio| SC

  SA --> GA["GitHub API"]
  SB --> PG["PostgreSQL"]
  SC --> FS["Local FS"]

(2) Message Flow (Tool-call example)

sequenceDiagram
  participant U as User
  participant H as Host (Kiro)
  participant C as MCP Client
  participant S as MCP Server
  participant E as External System

  U->>H: "Query my recent orders"
  H->>H: LLM reasons; decides to call query_orders Tool
  H->>C: Send tools/call request
  C->>S: JSON-RPC: tools/call {name: "query_orders", arguments: {...}}
  S->>E: SELECT * FROM orders WHERE ...
  E-->>S: Query results
  S-->>C: JSON-RPC Response: {content: [{type: "text", text: "..."}]}
  C-->>H: Return tool result
  H->>H: LLM integrates result and crafts answer
  H-->>U: "Your most recent 3 orders are..."

(3) Design Philosophy

Separation of concerns: Host handles LLM interaction; Client handles protocol; Server handles external systems.
1:1 sessions: each Client-Server pair maintains an isolated session; avoids cross-Server state pollution.
Progressive discovery: Client discovers capabilities first, calls only what's needed.
Security boundaries: Host controls Client permissions; Client controls Server access — layered isolation.

2.4. Eco-system

(1) Official SDKs (mid-2026)

Language	Package	Install
Python	`mcp`	`pip install mcp[cli]` or `uv add mcp`
TypeScript	`@modelcontextprotocol/sdk`	`npm install @modelcontextprotocol/sdk`
Kotlin	`io.modelcontextprotocol:kotlin-sdk`	Maven/Gradle
Go	Community-maintained	`go get`
Rust	Community-maintained	`cargo add`

(2) Higher-level Frameworks

Framework	Language	Notes
FastMCP (Python)	Python	Decorator syntax, auto-schema generation; 3.0 supports OpenTelemetry
FastMCP (TS)	TypeScript	TypeScript port; Express-style
FastAPI-MCP	Python	Auto-exposes FastAPI endpoints as MCP Tools
Spring AI MCP	Java	Spring ecosystem integration

(3) Major Client Support

Client	Type	Config path
Claude Desktop	Desktop App	`claude_desktop_config.json`
Claude Code	CLI Agent	`.claude/` or `~/.claude/`
Kiro	IDE (VS Code)	`.kiro/settings/mcp.json`
Cursor	IDE	`.cursor/mcp.json`
VS Code (Copilot)	IDE	`.vscode/mcp.json`
ChatGPT Desktop	Desktop App	Settings UI
Amazon Bedrock	Cloud	AgentCore Runtime
Windsurf / Roo Code	IDE	Per-tool path

(4) Server Discovery & Registry

Platform	URL	Notes
MCP Official Registry	github.com/modelcontextprotocol/registry	Official community registry
GitHub MCP Servers Repo	github.com/modelcontextprotocol/servers	Officially maintained Server list
mcp.run	mcp.run	Server hosting & discovery
mcpservers.org	mcpservers.org	Community Server directory
Pulse MCP	pulsemcp.com	Server search & ratings
Smithery	smithery.ai	Server marketplace
MCP Central	mcpcentral.io	Server registration & discovery

(5) Relationship with Agent Skills

MCP and Agent Skills are complementary layers (see 4.Protocol/1.Skill.md):
Agent Skills (SKILL.md): the "how" — workflow instructions, conventions, templates
MCP: the "what can be done" — tools, data sources, external connections
Function Calling: the "what can be called" — single tool-call schema
Typical collaboration: a Skill references MCP Tools. ```markdown ## Workflow (in SKILL.md)
Use the GitHub MCP Server's search_code Tool to find relevant code
Use the Filesystem MCP Server's read_file Tool to read files
Analyze the code and produce a review report ```
In Kiro: Skills live under .kiro/skills/; MCP is configured in .kiro/settings/mcp.json. They work together but are independent.

3. Install, Configure, Secure, & Cheatsheets

3.1. MCP Server Development — Python (FastMCP)

(1) Install

# Method 1: pip (recommended)
pip install "mcp[cli]"

# Method 2: uv (faster)
uv add "mcp[cli]"

# Method 3: FastMCP higher-level framework
pip install fastmcp

(2) Minimal Server (official SDK)

# server.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-server")

# Define a Tool
@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b

# Define a Resource
@mcp.resource("config://app")
def get_config() -> str:
    """Get application configuration."""
    return "App configuration data"

# Define a Prompt
@mcp.prompt()
def review_code(code: str) -> str:
    """Review the given code for issues."""
    return f"Please review this code:\n\n{code}"

if __name__ == "__main__":
    mcp.run()

# Run (stdio mode — for local Clients)
python server.py

# Run (HTTP mode — for remote Clients)
python server.py --transport streamable-http --port 8000

# Test with MCP Inspector
mcp dev server.py

(3) FastMCP Advanced Usage

from fastmcp import FastMCP

mcp = FastMCP("advanced-server")

# Annotated Tool — schema auto-generated
@mcp.tool()
def search_database(
    query: str,
    limit: int = 10,
    include_metadata: bool = False
) -> list[dict]:
    """Search the database with a natural-language query.

    Args:
        query: Natural-language search query
        limit: Maximum number of results to return
        include_metadata: Whether to include metadata in results
    """
    # actual DB query logic
    return [{"id": 1, "title": "Result 1"}]

# Dynamic Resource (URI Template)
@mcp.resource("users://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    """Get user profile by ID."""
    return f"Profile for user {user_id}"

# Prompt with arguments
@mcp.prompt()
def analyze_data(dataset: str, analysis_type: str = "summary") -> list:
    """Analyze a dataset with the specified analysis type."""
    return [
        {"role": "user", "content": f"Analyze {dataset} using {analysis_type} method"}
    ]

3.2. MCP Server Development — TypeScript

(1) Install

# Official SDK
npm install @modelcontextprotocol/sdk

# FastMCP TypeScript
npm install fastmcp

(2) Minimal Server

// server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "my-server",
  version: "1.0.0"
});

// Define a Tool
server.tool(
  "add",
  "Add two numbers together",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }]
  })
);

// Define a Resource
server.resource(
  "config",
  "config://app",
  async (uri) => ({
    contents: [{ uri: uri.href, text: "App configuration data" }]
  })
);

// Start
const transport = new StdioServerTransport();
await server.connect(transport);

# Run
npx tsx server.ts

# Test with Inspector
npx @modelcontextprotocol/inspector npx tsx server.ts

3.3. Client Configuration (per platform)

(1) Kiro

// .kiro/settings/mcp.json (project) or ~/.kiro/settings/mcp.json (global)
{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["path/to/server.py"],
      "env": {
        "API_KEY": "your-key"
      },
      "disabled": false,
      "autoApprove": ["add", "search_database"]
    },
    "remote-server": {
      "url": "https://my-server.example.com/mcp",
      "headers": {
        "Authorization": "Bearer token"
      }
    },
    "uvx-server": {
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

(2) Claude Desktop

// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    }
  }
}

(3) VS Code (Copilot)

// .vscode/mcp.json
{
  "servers": {
    "my-server": {
      "command": "python",
      "args": ["server.py"],
      "env": {}
    }
  }
}

(4) uvx Quick Start (on-demand load)

uvx is a tool from uv that runs Python packages directly without pre-installing.
Best practice for "load on demand": fetched when needed, no resource use when idle.

# Install uv (if missing)
brew install uv

# Run an MCP Server directly (no pip install)
uvx awslabs.aws-documentation-mcp-server@latest

# Configure uvx in mcp.json
# "command": "uvx", "args": ["package-name@latest"]

3.4. Scripts & Tools

(1) MCP Inspector — must-have for debugging

# Install
npm install -g @modelcontextprotocol/inspector

# Test local Server (stdio)
mcp dev server.py                          # Python Server
npx @modelcontextprotocol/inspector npx tsx server.ts  # TS Server

# Test remote Server (HTTP)
mcp dev --url https://my-server.example.com/mcp

# Inspector provides a Web UI:
# - Browse Tools/Resources/Prompts the Server exposes
# - Manually call a Tool and inspect results
# - View JSON-RPC message flow
# - Test parameter validation

(2) `mcp` CLI — official CLI

# Install (with Python SDK)
pip install "mcp[cli]"

# Create a new Server project
mcp create my-server

# Run Server
mcp run server.py

# Dev mode (with Inspector)
mcp dev server.py

# Install Server into Claude Desktop
mcp install server.py
mcp install server.py --name "My Server" --env API_KEY=xxx

(3) `uvx` — zero-install Server runner

# Run an official Server (no pre-install)
uvx awslabs.aws-documentation-mcp-server@latest
uvx mcp-server-fetch@latest
uvx mcp-server-git@latest

# Run a community Server
uvx mcp-server-sqlite@latest --db-path ./data.db

(4) Common Official MCP Servers

Server	Function	Install / run
server-filesystem	Filesystem I/O	`npx @modelcontextprotocol/server-filesystem /path`
server-github	GitHub API	`npx @modelcontextprotocol/server-github`
server-postgres	PostgreSQL queries	`npx @modelcontextprotocol/server-postgres`
server-sqlite	SQLite queries	`uvx mcp-server-sqlite --db-path ./db.sqlite`
server-fetch	HTTP requests	`uvx mcp-server-fetch`
server-git	Git operations	`uvx mcp-server-git`
server-puppeteer	Browser automation	`npx @modelcontextprotocol/server-puppeteer`
server-memory	Knowledge graph / memory	`npx @modelcontextprotocol/server-memory`
aws-documentation-server	AWS docs search	`uvx awslabs.aws-documentation-mcp-server@latest`

(5) Helper Scripts

# Quick MCP Server connection test (Python Client)
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def test_server():
    server_params = StdioServerParameters(
        command="python",
        args=["server.py"]
    )
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List all Tools
            tools = await session.list_tools()
            print(f"Available tools: {[t.name for t in tools.tools]}")

            # Call a Tool
            result = await session.call_tool("add", {"a": 1, "b": 2})
            print(f"Result: {result.content[0].text}")

asyncio.run(test_server())

# Quick Server health check (shell)
#!/bin/bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | python server.py 2>/dev/null | head -1 | python -m json.tool

3.5. Security Best Practices

(1) Auth & Authorization

Remote Servers must use OAuth 2.1 (per MCP spec).
Local Servers (stdio) rely on Host process isolation.
Tool-level permission: configure autoApprove for which Tools auto-execute; others require user confirmation.

(2) Security Checklist

[ ] No hard-coded credentials in mcp.json — use environment variables
[ ] Remote Servers: enable HTTPS + OAuth 2.1
[ ] Strict inputSchema for every Tool — defends against injection
[ ] Mark side-effecting Tools with readOnlyHint: false
[ ] Restrict Server's filesystem access (Roots)
[ ] Audit third-party Server code and permissions
[ ] In production, use autoApprove: [] (no auto-approval)

(3) Common Attack Vectors

Attack	Description	Defense
Prompt Injection	Malicious Resource content injects instructions	Server-side content filtering, Client-side sandbox
Tool Poisoning	Malicious Server impersonates a normal Tool	Only use Servers from trusted sources
Credential Leakage	API keys in env get logged	Use a Secret Manager; ban credential logging
Excessive Permissions	Server has too much filesystem access	Use Roots to restrict scope

3.6. Cheatsheets

(1) Development Workflow

# 1. Create Server
pip install "mcp[cli]"
mcp create my-server

# 2. Develop (edit server.py — add Tools/Resources/Prompts)

# 3. Test
mcp dev server.py              # Inspector

# 4. Configure on a Client
mcp install server.py          # install on Claude Desktop
# or manually edit .kiro/settings/mcp.json (Kiro)

# 5. Use
# Talk in the AI Client; Agent auto-discovers and calls Tools

(2) JSON-RPC Quick Reference

// List Tools
{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

// Call a Tool
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"add","arguments":{"a":1,"b":2}}}

// List Resources
{"jsonrpc":"2.0","id":3,"method":"resources/list","params":{}}

// Read a Resource
{"jsonrpc":"2.0","id":4,"method":"resources/read","params":{"uri":"file:///path/to/file"}}

// List Prompts
{"jsonrpc":"2.0","id":5,"method":"prompts/list","params":{}}

// Get a Prompt
{"jsonrpc":"2.0","id":6,"method":"prompts/get","params":{"name":"review_code","arguments":{"code":"..."}}}

(3) Configuration Templates

// stdio Server (local)
{
  "command": "python",
  "args": ["server.py"],
  "env": {"KEY": "value"}
}

// uvx Server (on-demand)
{
  "command": "uvx",
  "args": ["package-name@latest"],
  "env": {}
}

// npx Server (Node.js)
{
  "command": "npx",
  "args": ["-y", "@scope/server-name", "arg1"],
  "env": {}
}

// Remote Server (Streamable HTTP)
{
  "url": "https://server.example.com/mcp",
  "headers": {"Authorization": "Bearer token"}
}

4. Bootcamp & Workshops

4.1. Learning Resources

Resource	Type	Audience
MCP Official Docs	Spec	Everyone
MCP Quickstart	Tutorial	Beginners
Build First Server (chanl.ai)	Tutorial	Engineers
FastMCP Tutorial (firecrawl.dev)	Framework	Python developers
MCP Developer Guide (particula.tech)	Guide	Full-stack
MCP 2026 Guide (mcpfy.ai)	Year-in-review	Architects
WorkOS MCP Features Guide	Deep dive	Senior engineers
MCP Complete Guide (hyperion)	Guide	Security engineers
MCP Ecosystem Map	Overview	Decision-makers
AWS Bedrock MCP Blog	AWS integration	AWS users

4.2. Trouble Shooting

(1) Server cannot connect

Symptom: Client reports "Failed to connect to MCP server" or times out.
Diagnostics:
Confirm the Server runs standalone: python server.py or npx tsx server.ts.
Check the command path in mcp.json (absolute paths are more reliable).
Check env variables.
Test with Inspector: mcp dev server.py.
Check Server stderr (in stdio mode, stderr is the log).

(2) Tool not invoked by Agent

Cause: description not specific enough; the LLM can't match user intent.
Fix: include concrete trigger scenarios in the description — "Use this tool when the user asks about database queries" beats "Database tool".
Verify: manually call the Tool in Inspector to confirm it works.

(3) `uvx` command not found

Cause: uv not installed or not on PATH.
Fix: bash brew install uv # or curl -LsSf https://astral.sh/uv/install.sh | sh uvx --version

(4) Remote Server auth failure

Cause: OAuth 2.1 misconfigured or token expired.
Fix: check headers Authorization; confirm the token is valid.
Note: in Streamable HTTP, the Server must implement OAuth 2.1 endpoints.

(5) Resource content empty or malformed

Cause: URI mismatch or Server-side read failure.
Fix: test resources/read in Inspector; check the contents field.
Note: binary content must be Base64 encoded; text must be UTF-8.

(6) Tool name conflicts across multiple Servers

Cause: different Servers expose Tools with the same name.
Fix: prefix Tool names on the Server side (github_search, postgres_query).
Best practice: use domain_action naming.

4.3. Q & A

How is MCP different from a REST API?
REST is stateless request-response; MCP is stateful session.
REST requires the Client to know URLs and parameters; MCP supports auto-discovery.
REST is designed for human developers; MCP's Tool descriptions are written for LLMs.
They are not exclusive — MCP Servers usually call REST APIs internally.
How many Tools should an MCP Server expose?
Recommended: 5-15. Too many dilutes LLM accuracy.
Each Tool has a single responsibility; split complex operations into multiple Tools.
More than 20 → consider splitting into multiple Servers.
stdio or Streamable HTTP — which?
Local dev / IDE integration: stdio (simple, no network needed).
Team sharing / cloud deploy: Streamable HTTP (auth, scalable).
Hybrid: stdio in dev, HTTP in production.
Can an MCP Server call another MCP Server?
Yes. Internally a Server can act as a Client to another Server.
FastMCP 3.0 supports Server composition (mounting one Server inside another).
Beware of cycles.
How do MCP and Agent Skills work together?
Skills define the workflow ("first search code, then analyze, then produce a report").
MCP provides the tools (the "search code" action lives in the GitHub MCP Server).
In SKILL.md, reference MCP Tool names; the Agent calls them via MCP automatically.
See 4.Protocol/1.Skill.md §2.1(5) for the comparison table.
How do I quickly turn an existing REST API into an MCP Server?
Python: use FastAPI-MCP — one line wraps FastAPI endpoints as MCP Tools. python from fastapi_mcp import FastApiMCP mcp = FastApiMCP(app) # app is the FastAPI instance mcp.mount()
General: auto-generate from an OpenAPI spec (FastMCP 3.0 supports an OpenAPI Provider).
When do you write a Skill vs install an MCP?
One-liner: a Skill is the operations manual for the Agent; an MCP is external hands and feet connected to the Agent.
Write a Skill when teaching the Agent how to do something:
- Team conventions, multi-step workflows, knowledge consolidation, output templates
Install an MCP when giving the Agent something to do:
- Connect external systems, real-time data, take actions
Combine both (most common, most powerful): a Skill says "step 1: search code via GitHub; step 2: analyze; step 3: produce report"; the MCP provides the GitHub search.
Heuristic: if you write "please look up XXX data" inside a Skill, the lookup capability should come from MCP.
See 4.Protocol/1.Skill.md §2.1(5) for the three-way comparison.
Future direction of MCP?
2025-12: donated to the Linux Foundation AAIF — vendor-neutral governance.
2025-11: new Tasks primitive (async operations), Elicitation (user input collection).
2026+: standardized MCP Registry, enterprise governance, deep A2A integration.
Transport evolution: explore transport options better suited to enterprise-scale deployment.

2.MCP

I. MCP (Model Context Protocol)

1. Overview

1.1. Definition & Why

1.2. Features & Use Cases

(1) Core Features

(2) Typical Use Cases

1.3. Competitors & Alternatives

2. Concept, Component, & Architecture

2.1. Key Concepts

(1) JSON-RPC 2.0 — the foundation

(2) Three Primitives

(3) Capability Negotiation

(4) Transport

(5) Lifecycle

(6) Advanced Capabilities

2.2. Core Components

(1) MCP Host

(2) MCP Client

(3) MCP Server

(4) Tools

(5) Resources

(6) Prompts

2.3. Architecture & Design

(1) Overall Architecture

(2) Message Flow (Tool-call example)

(3) Design Philosophy

2.4. Eco-system

(1) Official SDKs (mid-2026)

(2) Higher-level Frameworks

(3) Major Client Support

(4) Server Discovery & Registry

(5) Relationship with Agent Skills

3. Install, Configure, Secure, & Cheatsheets

3.1. MCP Server Development — Python (FastMCP)

(1) Install

(2) Minimal Server (official SDK)

(3) FastMCP Advanced Usage

3.2. MCP Server Development — TypeScript

(1) Install

(2) Minimal Server

3.3. Client Configuration (per platform)

(1) Kiro

(2) Claude Desktop

(3) VS Code (Copilot)

(4) uvx Quick Start (on-demand load)

3.4. Scripts & Tools

(1) MCP Inspector — must-have for debugging

(2) mcp CLI — official CLI

(3) uvx — zero-install Server runner

(4) Common Official MCP Servers

(5) Helper Scripts

3.5. Security Best Practices

(1) Auth & Authorization

(2) Security Checklist

(3) Common Attack Vectors

3.6. Cheatsheets

(1) Development Workflow

(2) JSON-RPC Quick Reference

(3) Configuration Templates

4. Bootcamp & Workshops

4.1. Learning Resources

4.2. Trouble Shooting

(1) Server cannot connect

(2) Tool not invoked by Agent

(3) uvx command not found

(4) Remote Server auth failure

(5) Resource content empty or malformed

(6) Tool name conflicts across multiple Servers

4.3. Q & A

(2) `mcp` CLI — official CLI

(3) `uvx` — zero-install Server runner

(3) `uvx` command not found