Java MCP Annotations & APIs

A framework-agnostic Java library providing core annotations and APIs for implementing Model Context Protocol (MCP) servers and clients.

Overview

This repository provides common Java building blocks for MCP implementations without tying you to any specific runtime framework (Spring, Quarkus, Micronaut, WildFly, Open Liberty, etc.). It enables developers to create portable MCP integrations that can work across different Java ecosystems.

What is MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). It enables secure, controlled interactions between AI assistants and data sources, tools, and services.

Project Structure

mcp-server-api

Framework-agnostic annotations and interfaces for declaratively building MCP servers:

Tools:

• @Tool - Mark methods as MCP tools
• @ToolArg - Configure tool parameters
• ToolResponse - Full control over tool call responses (content, structured content, error status)

Package: org.mcpjava.server.tools

Resources:

• @Resource - Expose static resources
• @ResourceTemplate - Expose dynamic resources with URI templates
• @ResourceTemplateArg - Configure template URI variables
• ResourceResponse - Full control over resource read responses
• ResourceContents - Sealed interface for resource content (text or binary)
• TextResourceContents - Text resource content
• BlobResourceContents - Binary resource content

Package: org.mcpjava.server.resources

Prompts:

• @Prompt - Define reusable prompt templates
• @PromptArg - Configure prompt arguments
• PromptResponse - Full control over prompt responses
• PromptMessage - A single message within a prompt (role + content)

Package: org.mcpjava.server.prompts

Completion:

• @CompletePrompt - Provide completion for prompt arguments
• @CompleteResourceTemplate - Provide completion for resource template URIs
• @CompleteArg - Customize completion argument names
• CompletionResult - Completion response with suggestions, total count, and pagination
• CompletionContext - Access to other argument values already provided by the user

Package: org.mcpjava.server.completion

Content:

• ContentBlock - Sealed interface for content in responses (text, image, audio, embedded resource, resource link)
• TextContent - Text content block
• ImageContent - Image data content block
• AudioContent - Audio data content block
• EmbeddedResource - Content block embedding a resource with its data
• ResourceLink - Content block linking to a resource by URI
• Annotations - Metadata annotations for content and resources (audience, priority, last modified)

Package: org.mcpjava.server.content

Progress:

• Progress - Access to progress reporting capabilities, injectable into tool/prompt/resource methods