a1048b9342Copy and convert existing MCP documentation into an embedded docs site using MkDocs with Material theme. Includes client and server guides, quickstart, development/contributing docs, architecture diagrams, and a GitHub Actions workflow for publishing to GitHub Pages. --------- Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
131 lines
7.2 KiB
Markdown
131 lines
7.2 KiB
Markdown
---
|
|
title: Overview
|
|
description: Introduction to the Model Context Protocol (MCP) Java SDK
|
|
---
|
|
|
|
# MCP Java SDK
|
|
|
|
Java SDK for the [Model Context Protocol](https://modelcontextprotocol.io/docs/concepts/architecture)
|
|
enables standardized integration between AI models and tools.
|
|
|
|
## Features
|
|
|
|
- MCP Client and MCP Server implementations supporting:
|
|
- Protocol [version compatibility negotiation](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#initialization) with multiple protocol versions
|
|
- [Tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools) discovery, execution, list change notifications, and structured output with schema validation
|
|
- [Resources](https://modelcontextprotocol.io/specification/2025-11-25/server/resources) management with URI templates
|
|
- [Roots](https://modelcontextprotocol.io/specification/2025-11-25/client/roots) list management and notifications
|
|
- [Prompts](https://modelcontextprotocol.io/specification/2025-11-25/server/prompts) handling and management
|
|
- [Sampling](https://modelcontextprotocol.io/specification/2025-11-25/client/sampling) support for AI model interactions
|
|
- [Elicitation](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation) support for requesting user input from servers
|
|
- [Completions](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/completion) for argument autocompletion suggestions
|
|
- [Progress](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/progress) - progress notifications for tracking long-running operations
|
|
- [Logging](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/logging) - structured logging with configurable severity levels
|
|
- Multiple transport implementations:
|
|
- Default transports (included in core `mcp` module, no external web frameworks required):
|
|
- [STDIO](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#stdio)-based transport for process-based communication
|
|
- Java HttpClient-based SSE client transport for HTTP SSE Client-side streaming
|
|
- Servlet-based SSE server transport for HTTP SSE Server streaming
|
|
- [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http) transport for efficient bidirectional communication (client and server)
|
|
- Optional Spring-based transports (convenience if using Spring Framework):
|
|
- WebFlux SSE client and server transports for reactive HTTP streaming
|
|
- WebFlux Streamable HTTP server transport
|
|
- WebMVC SSE server transport for servlet-based HTTP streaming
|
|
- WebMVC Streamable HTTP server transport
|
|
- WebMVC Stateless server transport
|
|
- Supports Synchronous and Asynchronous programming paradigms
|
|
- Pluggable JSON serialization (Jackson 2.x and Jackson 3.x)
|
|
- Pluggable authorization hooks for server security
|
|
- DNS rebinding protection with Host/Origin header validation
|
|
|
|
!!! tip
|
|
The core `io.modelcontextprotocol.sdk:mcp` module provides default STDIO, SSE, and Streamable HTTP client and server transport implementations without requiring external web frameworks.
|
|
|
|
Spring-specific transports are available as optional dependencies for convenience when using the [MCP Client Boot Starter](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html) and [MCP Server Boot Starter](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html).
|
|
Also consider the [MCP Annotations](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-annotations-overview.html) and [MCP Security](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-security.html).
|
|
|
|
## Architecture
|
|
|
|
The SDK follows a layered architecture with clear separation of concerns:
|
|
|
|
|
|
|
|
- **Client/Server Layer (McpClient/McpServer)**: Both use McpSession for sync/async operations,
|
|
with McpClient handling client-side protocol operations and McpServer managing server-side protocol operations.
|
|
- **Session Layer (McpSession)**: Manages communication patterns and state.
|
|
- **Transport Layer (McpTransport)**: Handles JSON-RPC message serialization/deserialization via:
|
|
- StdioTransport (stdin/stdout) in the core module
|
|
- HTTP SSE transports in dedicated transport modules (Java HttpClient, Spring WebFlux, Spring WebMVC)
|
|
- Streamable HTTP transports for efficient bidirectional communication
|
|
|
|
The MCP Client is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers.
|
|
It implements the client-side of the protocol.
|
|
|
|
|
|
|
|
The MCP Server is a foundational component in the Model Context Protocol (MCP) architecture that provides tools, resources, and capabilities to clients.
|
|
It implements the server-side of the protocol.
|
|
|
|
|
|
|
|
Key Interactions:
|
|
|
|
- **Client/Server Initialization**: Transport setup, protocol compatibility check, capability negotiation, and implementation details exchange.
|
|
- **Message Flow**: JSON-RPC message handling with validation, type-safe response processing, and error handling.
|
|
- **Resource Management**: Resource discovery, URI template-based access, subscription system, and content retrieval.
|
|
|
|
## Module Structure
|
|
|
|
The SDK is organized into modules to separate concerns and allow adopters to bring in only what they need:
|
|
|
|
| Module | Artifact ID | Purpose |
|
|
|--------|------------|---------|
|
|
| `mcp-bom` | `mcp-bom` | Bill of Materials for dependency management |
|
|
| `mcp-core` | `mcp-core` | Core reference implementation (STDIO, JDK HttpClient, Servlet, Streamable HTTP) |
|
|
| `mcp-json-jackson2` | `mcp-json-jackson2` | Jackson 2.x JSON serialization implementation |
|
|
| `mcp-json-jackson3` | `mcp-json-jackson3` | Jackson 3.x JSON serialization implementation |
|
|
| `mcp` | `mcp` | Convenience bundle (`mcp-core` + `mcp-json-jackson3`) |
|
|
| `mcp-test` | `mcp-test` | Shared testing utilities and integration tests |
|
|
| `mcp-spring-webflux` | `mcp-spring-webflux` | Spring WebFlux integration (SSE and Streamable HTTP) |
|
|
| `mcp-spring-webmvc` | `mcp-spring-webmvc` | Spring WebMVC integration (SSE and Streamable HTTP) |
|
|
|
|
!!! tip
|
|
A minimal adopter may depend only on `mcp` (core + Jackson 3), while a Spring-based application can add `mcp-spring-webflux` or `mcp-spring-webmvc` for deeper framework integration.
|
|
|
|
## Next Steps
|
|
|
|
<div class="grid cards" markdown>
|
|
|
|
- :rocket:{ .lg .middle } **Quickstart**
|
|
|
|
---
|
|
|
|
Get started with dependencies and BOM configuration.
|
|
|
|
[:octicons-arrow-right-24: Quickstart](quickstart.md)
|
|
|
|
- :material-monitor:{ .lg .middle } **MCP Client**
|
|
|
|
---
|
|
|
|
Learn how to create and configure MCP clients.
|
|
|
|
[:octicons-arrow-right-24: Client](client.md)
|
|
|
|
- :material-server:{ .lg .middle } **MCP Server**
|
|
|
|
---
|
|
|
|
Learn how to implement and configure MCP servers.
|
|
|
|
[:octicons-arrow-right-24: Server](server.md)
|
|
|
|
- :fontawesome-brands-github:{ .lg .middle } **GitHub**
|
|
|
|
---
|
|
|
|
View the source code and contribute.
|
|
|
|
[:octicons-arrow-right-24: Repository](https://github.com/modelcontextprotocol/java-sdk)
|
|
|
|
</div>
|