mcp-learning

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

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