mcp-learning

Model Context Protocol (MCP) — Learning Reference

Source: modelcontextprotocol/modelcontextprotocol Spec versions: 2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25 (latest) Date: 2026-06-26

Architecture

MCP defines a three-party model:

Party	Role	Control
Host	LLM application (IDE, chat client)	Orchestrator
Client	Connector within the host	Manages sessions
Server	External data/tool service	Provides primitives

Inspired by the Language Server Protocol. Standardizes how to integrate context and tools into AI applications.

Three Primitives

Primitive	Control	Purpose	Example
Prompts	User-controlled	Interactive templates invoked by user choice	Slash commands, menu options
Resources	Application-controlled	Contextual data attached and managed by the client	File contents, git history
Tools	Model-controlled	Functions exposed to the LLM to take actions	API calls, file writing

Client-Server Features

Server offers to client: Resources, Prompts, Tools, Logging, Completions, Tasks

Client offers to server: Sampling (LLM calls), Roots (filesystem boundaries), Elicitation (user prompts)

Transports

stdio (recommended)

• Client launches server as subprocess
• Server reads JSON-RPC from stdin, writes to stdout
• Messages newline-delimited, no embedded newlines
• stderr for logging (optional, may be ignored)

Streamable HTTP (2025-03-26+, replaces old HTTP+SSE)

• Single HTTP endpoint supporting POST and GET
• POST sends JSON-RPC messages
• Server returns either application/json or text/event-stream (SSE)
• GET opens SSE stream for server-to-client messages
• Session via MCP-Session-Id header (UUID from init response)
• Protocol version via MCP-Protocol-Version header

Old HTTP+SSE (2024-11-05, deprecated)

• Two separate endpoints: SSE endpoint (GET) + POST endpoint
• Server opens SSE stream for notifications
• Client sends POST requests to POST endpoint
• This is what MermaidChart uses

Protocol Versions

Version	Key Changes
2024-11-05	Initial release, HTTP+SSE transport
2025-03-26	Streamable HTTP transport, security updates
2025-06-18	Minor spec refinements
2025-11-25	Latest — tasks, elicitation, schema improvements

Clients SHOULD send the latest supported version. Server responds with its latest supported version if different. Client disconnects if versions don’t overlap.

JSON-RPC 2.0 Message Types

MCP uses JSON-RPC 2.0. All messages MUST be UTF-8 encoded.

Request (client -> server)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": { "cursor": "optional" }
}

• MUST include string or integer ID (never null)
• ID MUST NOT have been used before in the same session

Result Response (success)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { "tools": [...] }
}

• MUST include same ID as request
• MUST include result field

Error Response (failure)

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Unknown tool: invalid_name"
  }
}

• MUST include same ID as request (except unreadable malformed requests)
• MUST include error with code (integer) and message

Notification (one-way, no response)

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

• MUST NOT include an ID

Lifecycle

Client --initialize--> Server
Server --initialize response--> Client
Client --initialized notification--> Server
[Operation phase: tools/list, tools/call, resources/read, prompts/list, etc.]
Client --disconnect (close transport)--

Initialization Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "hermes", "version": "1.0" }
  }
}

Initialization Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": { "listChanged": true }
    },
    "serverInfo": {
      "name": "Mermaid Server",
      "version": "1.0.0"
    }
  }
}

• Response header includes MCP-Session-Id (UUID) on HTTP transport
• Client MUST send notifications/initialized after receiving response
• Client MUST NOT send other requests before server responds to initialize
• Server MUST NOT send requests before receiving initialized notification

Tool Model

Tools are the most commonly used MCP primitive. Servers expose callable functions.

Tool Definition

{
  "name": "get_weather",
  "title": "Weather Information",
  "description": "Get current weather for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": { "type": "string", "description": "City name or zip code" }
    },
    "required": ["location"]
  },
  "icons": [...],
  "execution": { "taskSupport": "optional" }
}

Tool Name Rules

• 1-128 characters
• Only A-Z, a-z, 0-9, underscore, hyphen, dot
• No spaces, commas, or special characters
• Case-sensitive
• Unique within a server

Tool Result Content

Results contain a content array with items:

Type	Use
text	Plain text output
image	Base64-encoded image + mimeType
audio	Base64-encoded audio + mimeType
resource_link	URI to an external resource
resource	Embedded resource with full content

Results also include isError: true/false flag.

Listing and Calling Tools

Client -> Server: tools/list
Server -> Client: { tools: [...] }

Client -> Server: tools/call { name: "get_weather", arguments: { location: "NYC" } }
Server -> Client: { content: [{ type: "text", text: "..." }], isError: false }

Servers may emit notifications/tools/list_changed when the list changes.

Security Model

Principle	Detail
User consent	Users must explicitly consent to all data access and operations
Data privacy	Hosts must obtain consent before exposing user data to servers
Tool safety	Tools = arbitrary code execution; user consent required before invocation
LLM sampling	Users must approve any LLM sampling requests from servers
DNS rebinding	Servers MUST validate Origin header (HTTP transport)
Local binding	Servers SHOULD bind to localhost only

Protocol Evolution: 2024-11-05 vs 2025-11-25

Feature	2024-11-05	2025-11-25
Transports	stdio, HTTP+SSE (2 endpoints)	stdio, Streamable HTTP (1 endpoint)
Session	No official session management	MCP-Session-Id header
Protocol version header	None	MCP-Protocol-Version header
Elicitation	Not defined	Client feature
Tasks	Not defined	Full task-augmented execution
Sampling	Not defined	Client feature
Roots	Not defined	Client feature
Logging	Not defined	Server feature
Completions	Not defined	Server feature
Resumability	Not defined	Last-Event-ID for SSE streams
Schema dialect	Not specified	JSON Schema 2020-12 default
_meta field	Not defined	Reserved metadata namespace
icons field	Not defined	Standardized icon metadata

Backwards Compatibility

New transport (2025+): POST InitializeRequest with Accept header. If 400/404/405, fall back to old HTTP+SSE: GET returns SSE with endpoint event.

SEP (Suggested Enhancement Proposal) Index

The spec repo tracks Seps for protocol evolution. Key ones:

SEP	Topic
#1330	Elicitation enum schema improvements
#1577	Sampling with tools
#1686	Tasks
#1730	SDKs tiering system
#2085	Governance succession and amendment
#2133	Extensions
#2243	HTTP standardization
#2575	Stateless MCP
#2576	Sessionless MCP
#2596	Spec feature lifecycle and deprecation
#2663	Tasks extension

Real Server: MermaidChart MCP

URL: https://mcp.mermaidchart.com/mcp Spec version: 2024-11-05 (HTTP+SSE transport) Server identity: Mermaid Server v1.0.0 Third-party: Not part of satware AG / IPADP ecosystem

Protocol Behavior

Aspect	Behavior
Transport	HTTP+SSE (2024-11-05 style)
Session	Custom mcp-session-id header (lowercase, not MCP-Session-Id)
Session header on requests	Mcp-Session-Id (mixed case)
Accept header	application/json, text/event-stream (required)
Session init	initialize -> capture mcp-session-id from response header -> notifications/initialized

Tools (17 total)

Mermaid diagram tools (5):

Tool	What it does	Tested
validate_and_render_mermaid_diagram	Renders diagram to PNG, returns image + code + preview link	Actual rendering
get_diagram_title	Returns LLM prompts for title generation	Prompt-only (delegates to client LLM)
get_diagram_summary	Returns LLM prompts for summary generation	Prompt-only (delegates to client LLM)
search_mermaid_icons	Search AWS/Azure/GCP/FontAwesome icons	Returns icon list
get_mermaid_syntax_document	Returns full Mermaid.js syntax docs for a diagram type	Returns documentation

GitHub tools (12): Require Github-Token header or GITHUB_TOKEN env var on server. list_repos, list_mermaid_files, read_mermaid_file, create_pr, push_file, list_pulls, list_branches, list_issues, create_issue, get_issue_comments, get_pull_comments, list_tools

Key Observation: Prompt-Only Tools

get_diagram_title and get_diagram_summary do NOT generate titles/summaries themselves. They return the system/user prompts for the client LLM to perform the generation. This is a design pattern — the server provides the framework, the client LLM does the creative work.

Icon Search Result Format

{
  "query": "s3",
  "provider": "aws",
  "results": [{ "provider": "aws", "icons": ["aws:arch-amazon-s3-on-outposts", ...], "total": 837 }],
  "availableProviders": [
    { "name": "aws", "prefix": "aws", "packageName": "@mermaid-chart/icons-aws" },
    { "name": "azure", "prefix": "azure", "packageName": "@mermaid-chart/icons-azure" },
    { "name": "gcp", "prefix": "gcp", "packageName": "@mermaid-chart/icons-gcp" },
    { "name": "fa", "prefix": "fa", "packageName": "@iconify-json/fa6-regular" }
  ]
}

All Icon Providers

Prefix	Provider	Package
aws:	Amazon Web Services	@mermaid-chart/icons-aws
azure:	Microsoft Azure	@mermaid-chart/icons-azure
gcp:	Google Cloud Platform	@mermaid-chart/icons-gcp
fa:	FontAwesome Regular	@iconify-json/fa6-regular

Icon Usage Syntax

flowchart TB
    A["EC2 Instance"]@{ icon: "aws:arch-amazon-ec2", pos: "t", h: 48 }
    B["RDS Database"]@{ icon: "aws:arch-amazon-rds", pos: "t", h: 48 }
    A --> B

Mermaid Diagram Types (via get_mermaid_syntax_document)

flowchart, flowchart-v2, flowchart-elk, sequence, class, classDiagram, er, gantt, pie, journey, gitGraph, c4, stateDiagram, state, mindmap, timeline, sankey, xychart, quadrant, requirement, architecture, block, packet, kanban, radar, treemap, venn, zenuml, zenUML, graph, erDiagram, sequenceDiagram, userJourney, xyChart, quadrantChart, requirementDiagram, entityRelationshipDiagram, gitgraph

Session Management (MermaidChart-specific)

The MermaidChart server uses a custom header naming convention that differs from the 2025 spec:

Step	Header	Case
Response (from server)	mcp-session-id	lowercase
Request (to server)	Mcp-Session-Id	mixed case
2025 spec standard	MCP-Session-Id	all caps

This is a 2024-11-05 server that predates the standardized header naming.

Curl Session Template

# 1. Initialize
RAW=$(curl -s -D - -X POST 'https://<server>/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"hermes","version":"1.0"}}}')

# 2. Extract session ID
SESSION_ID=$(echo "$RAW" | grep -i '^mcp-session-id:' | sed 's/^mcp-session-id: *//;s/\r$//')

# 3. Send initialized notification
curl -s -X POST 'https://<server>/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' > /dev/null

# 4. Call tools
curl -s -X POST 'https://<server>/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"<tool>","arguments":{"<param>":"<value>","clientName":"hermes"}}}'

References

• Official spec: ~/external/modelcontextprotocol/ (GitHub)
• Spec docs: docs/specification/2025-11-25/ (MDX)
• TypeScript schema: schema/2025-11-25/schema.ts
• SEPs: seps/ directory (28+ proposals)
• MermaidChart probe: learn/mcp/mermaid-chart-mcp.md (detailed server-specific notes)
• IPADP: This repo is L1 conformance; learn is a learning branch, no upstream/downstream dependency