Skip to content

Documentation Development

This guide covers how to set up and preview the MCP Java SDK documentation locally.

Prerequisites

  • Python 3.x
  • pip (Python package manager)

Setup

Install mkdocs-material:

pip install mkdocs-material

Preview Locally

From the project root directory, run:

mkdocs serve

A local preview of the documentation will be available at http://localhost:8000.

Custom Ports

By default, mkdocs uses port 8000. You can customize the port with the -a flag:

mkdocs serve -a localhost:3333

Building

To build the static site for deployment:

mkdocs build

The built site will be output to the site/ directory.

Project Structure

docs/
├── index.md            # Home page
├── overview.md         # Architecture and modules
├── quickstart.md       # Quickstart guide
├── client-modern.md    # MCP Client, modern (2026-07-28)
├── server-modern.md    # MCP Server, modern (2026-07-28)
├── client.md           # MCP Client, legacy (2025-11-25 and earlier)
├── server.md           # MCP Server, legacy (2025-11-25 and earlier)
├── contribute.md       # Contributing guide
├── development.md      # This page
├── blog/               # Blog posts
└── images/             # Images and diagrams
mkdocs.yml              # MkDocs configuration

Writing Guidelines

  • Documentation pages use standard Markdown with mkdocs-material extensions
  • Use content tabs (=== "Tab Label") for Maven/Gradle or Sync/Async code examples
  • Use admonitions (!!! tip, !!! info, !!! warning) for callouts
  • All code blocks should specify a language for syntax highlighting
  • Images go in the docs/images/ directory

IDE Support

We suggest using extensions on your IDE to recognize and format Markdown. If you're a VSCode user, consider the Markdown All in One extension for enhanced Markdown support, and Prettier for code formatting.