Implement Model Context Protocol (MCP) servers with LangChain4j to extend AI capabilities with standardized tools, resources, and prompt templates.
Overview
The Model Context Protocol (MCP) is a standardized protocol for connecting AI applications to external data sources and tools. LangChain4j provides MCP server implementation patterns that enable AI systems to dynamically discover and execute tools, access resources, and use prompt templates through a standardized interface.
When to Use
Use this skill when building:
AI applications requiring external tool integration
Enterprise MCP servers with multi-domain support (GitHub, databases, APIs)
Dynamic tool providers with context-aware filtering
Resource-based data access systems for AI models
Prompt template servers for standardized AI interactions
Scalable AI agents with resilient tool execution
Multi-modal AI applications with diverse data sources
Spring Boot applications with MCP integration
Production-ready MCP servers with security and monitoring
Instructions
Follow these steps to implement an MCP server with LangChain4j:
1. Create Tool Provider
Implement
ToolProvider
to define executable tools:
class
WeatherToolProvider
implements
ToolProvider
{
@Override
public
List
<
ToolSpecification
>
listTools
(
)
{
return
List
.
of
(
ToolSpecification
.
builder
(
)
.
name
(
"get_weather"
)
.
description
(
"Get weather for a city"
)
.
inputSchema
(
Map
.
of
(
"type"
,
"object"
,
"properties"
,
Map
.
of
(
"city"
,
Map
.
of
(
"type"
,
"string"
,
"description"
,
"City name"
)
)
,
"required"
,
List
.
of
(
"city"
)
)
)
.
build
(
)
)
;
}
@Override
public
String
executeTool
(
String
name
,
String
arguments
)
{
// Parse arguments and execute tool logic
return
"Weather data result"
;
}
}
2. Configure MCP Server
Create and start the MCP server:
MCPServer
server
=
MCPServer
.
builder
(
)
.
server
(
new
StdioServer
.
Builder
(
)
)
.
addToolProvider
(
new
WeatherToolProvider
(
)
)
.
build
(
)
;
server
.
start
(
)
;
3. Add Resource Provider
Implement resource providers for data access:
class
CompanyResourceProvider
implements
ResourceListProvider
,
ResourceReadHandler
{
@Override
public
List
<
McpResource
>
listResources
(
)
{
return
List
.
of
(
McpResource
.
builder
(
)
.
uri
(
"policies"
)
.
name
(
"Company Policies"
)
.
mimeType
(
"text/plain"
)
.
build
(
)
)
;
}
@Override
public
String
readResource
(
String
uri
)
{
return
loadResourceContent
(
uri
)
;
}
}
4. Integrate with Spring Boot
Configure MCP server in Spring Boot application:
@Bean
public
MCPSpringConfig
mcpServer
(
List
<
ToolProvider
>
tools
)
{
return
MCPSpringConfig
.
builder
(
)
.
tools
(
tools
)
.
server
(
new
StdioServer
.
Builder
(
)
)
.
build
(
)
;
}
5. Implement Security
Add tool filtering for access control:
McpToolProvider
secureProvider
=
McpToolProvider
.
builder
(
)
.
mcpClients
(
mcpClient
)
.
filter
(
(
client
,
tool
)
->
{
if
(
tool
.
name
(
)
.
startsWith
(
"admin_"
)
&&
!
isAdmin
(
)
)
{
return
false
;
}
return
true
;
}
)
.
build
(
)
;
Quick Start
Basic MCP Server
Create a simple MCP server with one tool:
MCPServer
server
=
MCPServer
.
builder
(
)
.
server
(
new
StdioServer
.
Builder
(
)
)
.
addToolProvider
(
new
SimpleWeatherToolProvider
(
)
)
.
build
(
)
;
server
.
start
(
)
;
Spring Boot Integration
Configure MCP server in Spring Boot:
@Bean
public
MCPSpringConfig
mcpServer
(
List
<
ToolProvider
>
tools
)
{
return
MCPSpringConfig
.
builder
(
)
.
tools
(
tools
)
.
server
(
new
StdioServer
.
Builder
(
)
)
.
build
(
)
;
}
Core Concepts
MCP Architecture
MCP standardizes AI application connections:
Tools
Executable functions (database queries, API calls)
Resources
Data sources (files, schemas, documentation)
Prompts
Pre-configured templates for tasks
Transport
Communication layer (stdio, HTTP, WebSocket)
AI Application ←→ MCP Client ←→ Transport ←→ MCP Server ←→ External Service
Key Components
MCPServer
Main server instance with configuration
ToolProvider
Tool specification and execution interface
ResourceListProvider/ResourceReadHandler
Resource access
PromptListProvider/PromptGetHandler
Template management
Transport
Communication mechanisms (stdio, HTTP)
Implementation Patterns
Tool Provider Pattern
Create tools with proper schema validation:
class
WeatherToolProvider
implements
ToolProvider
{
@Override
public
List
<
ToolSpecification
>
listTools
(
)
{
return
List
.
of
(
ToolSpecification
.
builder
(
)
.
name
(
"get_weather"
)
.
description
(
"Get weather for a city"
)
.
inputSchema
(
Map
.
of
(
"type"
,
"object"
,
"properties"
,
Map
.
of
(
"city"
,
Map
.
of
(
"type"
,
"string"
,
"description"
,
"City name"
)
)
,
"required"
,
List
.
of
(
"city"
)
)
)
.
build
(
)
)
;
}
@Override
public
String
executeTool
(
String
name
,
String
arguments
)
{
// Parse arguments and execute tool logic
return
"Weather data result"
;
}
}
Resource Provider Pattern
Provide static and dynamic resources:
class
CompanyResourceProvider
implements
ResourceListProvider
,
ResourceReadHandler
{
@Override
public
List
<
McpResource
>
listResources
(
)
{
return
List
.
of
(
McpResource
.
builder
(
)
.
uri
(
"policies"
)
.
name
(
"Company Policies"
)
.
mimeType
(
"text/plain"
)
.
build
(
)
)
;
}
@Override
public
String
readResource
(
String
uri
)
{
return
loadResourceContent
(
uri
)
;
}
}
Prompt Template Pattern
Create reusable prompt templates:
class
PromptTemplateProvider
implements
PromptListProvider
,
PromptGetHandler
{
@Override
public
List
<
Prompt
>
listPrompts
(
)
{
return
List
.
of
(
Prompt
.
builder
(
)
.
name
(
"code-review"
)
.
description
(
"Review code for quality"
)
.
build
(
)
)
;
}
@Override
public
String
getPrompt
(
String
name
,
Map
<
String
,
String
>
args
)
{
return
applyTemplate
(
name
,
args
)
;
}
}
Transport Configuration
Stdio Transport
Local process communication:
McpTransport
transport
=
new
StdioMcpTransport
.
Builder
(
)
.
command
(
List
.
of
(
"npm"
,
"exec"
,
"@modelcontextprotocol/server-everything@0.6.2"
)
)
.
logEvents
(
true
)
.
build
(
)
;
HTTP Transport
Remote server communication:
McpTransport
transport
=
new
HttpMcpTransport
.
Builder
(
)
.
sseUrl
(
"http://localhost:3001/sse"
)
.
logRequests
(
true
)
.
logResponses
(
true
)
.
build
(
)
;
Client Integration
MCP Client Setup
Connect to MCP servers:
McpClient
client
=
new
DefaultMcpClient
.
Builder
(
)
.
key
(
"my-client"
)
.
transport
(
transport
)
.
cacheToolList
(
true
)
.
build
(
)
;
// List available tools
List
<
ToolSpecification
>
tools
=
client
.
listTools
(
)
;
Tool Provider Integration
Bridge MCP servers to LangChain4j AI services:
McpToolProvider
provider
=
McpToolProvider
.
builder
(
)
.
mcpClients
(
mcpClient
)
.
failIfOneServerFails
(
false
)
.
filter
(
(
client
,
tool
)
->
filterByPermissions
(
tool
)
)
.
build
(
)
;
// Integrate with AI service
AIAssistant
assistant
=
AiServices
.
builder
(
AIAssistant
.
class
)
.
chatModel
(
chatModel
)
.
toolProvider
(
provider
)
.
build
(
)
;
Security & Best Practices
Tool Security
Implement secure tool filtering:
McpToolProvider
secureProvider
=
McpToolProvider
.
builder
(
)
.
mcpClients
(
mcpClient
)
.
filter
(
(
client
,
tool
)
->
{
if
(
tool
.
name
(
)
.
startsWith
(
"admin_"
)
&&
!
isAdmin
(
)
)
{
return
false
;
}
return
true
;
}
)
.
build
(
)
;
Resource Security
Apply access controls to resources:
public
boolean
canAccessResource
(
String
uri
,
User
user
)
{
return
resourceService
.
hasAccess
(
uri
,
user
)
;
}
Error Handling
Implement robust error handling:
try
{
String
result
=
mcpClient
.
executeTool
(
request
)
;
}
catch
(
McpException
e
)
{
log
.
error
(
"MCP execution failed: {}"
,
e
.
getMessage
(
)
)
;
return
fallbackResult
(
)
;
}
Advanced Patterns
Multi-Server Configuration
Configure multiple MCP servers:
@Bean
public
List
<
McpClient
>
mcpClients
(
List
<
ServerConfig
>
configs
)
{
return
configs
.
stream
(
)
.
map
(
this
::
createMcpClient
)
.
collect
(
Collectors
.
toList
(
)
)
;
}
@Bean
public
McpToolProvider
multiServerProvider
(
List
<
McpClient
>
clients
)
{
return
McpToolProvider
.
builder
(
)
.
mcpClients
(
clients
)
.
failIfOneServerFails
(
false
)
.
build
(
)
;
}
Dynamic Tool Discovery
Runtime tool filtering based on context:
McpToolProvider
contextualProvider
=
McpToolProvider
.
builder
(
)
.
mcpClients
(
clients
)
.
filter
(
(
client
,
tool
)
->
isToolAllowed
(
user
,
tool
,
context
)
)
.
build
(
)
;
Health Monitoring
Monitor MCP server health:
@Component
public
class
McpHealthChecker
{
@Scheduled
(
fixedRate
=
30000
)
// 30 seconds
public
void
checkServers
(
)
{
mcpClients
.
forEach
(
client
->
{
try
{
client
.
listTools
(
)
;
markHealthy
(
client
.
key
(
)
)
;
}
catch
(
Exception
e
)
{
markUnhealthy
(
client
.
key
(
)
,
e
.
getMessage
(
)
)
;
}
}
)
;
}
}
Configuration
Application Properties
Configure MCP servers in application.yml:
mcp
:
servers
:
github
:
type
:
docker
command
:
[
"/usr/local/bin/docker"
,
"run"
,
"-e"
,
"GITHUB_TOKEN"
,
"-i"
,
"mcp/github"
]
log-events
:
true
database
:
type
:
stdio
command
:
[
"/usr/bin/npm"
,
"exec"
,
"@modelcontextprotocol/server-sqlite@0.6.2"
]
log-events
:
false
Spring Boot Configuration
Configure MCP with Spring Boot:
@Configuration
@EnableConfigurationProperties
(
McpProperties
.
class
)
public
class
McpConfiguration
{
@Bean
public
MCPServer
mcpServer
(
List
<
ToolProvider
>
providers
)
{
return
MCPServer
.
builder
(
)
.
server
(
new
StdioServer
.
Builder
(
)
)
.
addToolProvider
(
providers
)
.
enableLogging
(
true
)
.
build
(
)
;
}
}
Examples
Example 1: Weather Tool Execution
Input:
// Client invokes the weather tool
Map
<
String
,
Object
>
args
=
Map
.
of
(
"city"
,
"Milan"
)
;
String
result
=
mcpClient
.
executeTool
(
"get_weather"
,
mapper
.
writeValueAsString
(
args
)
)
;
Output:
{
"city"
:
"Milan"
,
"temperature"
:
22
,
"condition"
:
"Partly Cloudy"
,
"humidity"
:
65
,
"unit"
:
"celsius"
}
Example 2: Resource Retrieval
Input:
// Client requests a resource by URI
String
content
=
mcpClient
.
readResource
(
"policies"
)
;
Output:
Company Remote Work Policy v2.0
Effective Date: January 1, 2025
1. Employees may work remotely up to 3 days per week...
Example 3: Multi-Server Tool Discovery
Input:
// List all tools from connected MCP servers
List
<
ToolSpecification
>
tools
=
mcpToolProvider
.
tools
(
)
;
tools
.
forEach
(
t
->
System
.
out
.
println
(
t
.
name
(
)
+
": "
+
t
.
description
(
)
)
)
;
Output:
get_weather: Get current weather for a city
search_documents: Search company knowledge base
send_notification: Send notification to user
admin_backup: Create system backup (admin only)
Refer to
examples.md
for comprehensive implementation examples including:
Basic MCP server setup
Multi-tool enterprise servers
Resource and prompt providers
Spring Boot integration
Error handling patterns
Security implementations
API Reference
Complete API documentation is available in
api-reference.md
covering:
Core MCP classes and interfaces
Transport configuration
Client and server patterns
Error handling strategies
Configuration management
Testing and validation
Best Practices
Resource Management
Always close MCP clients properly using try-with-resources
Error Handling
Implement graceful degradation when servers fail
Security
Use tool filtering and resource access controls
Performance
Enable caching and optimize tool execution
Monitoring
Implement health checks and observability
Testing
Create comprehensive test suites with mocks
Documentation
Document tools, resources, and prompts clearly
Configuration
Use structured configuration for maintainability
References
LangChain4j Documentation
Model Context Protocol Specification
API Reference
Examples
Constraints and Warnings
MCP servers should implement proper resource cleanup when stopped.
External MCP Server Security
Only connect to trusted, verified MCP servers; external servers (including those launched via
npm exec
or HTTP/SSE endpoints) can expose untrusted tools, resources, and prompts that may influence agent behavior through indirect prompt injection.
Pin MCP Server Versions
Always pin npm packages to specific versions (e.g.,
@modelcontextprotocol/server-everything@0.6.2
) to prevent supply-chain attacks from unpinned dependencies.
Validate External Content
Content retrieved from MCP server resources (e.g., GitHub issues, database records) is untrusted user-generated data; validate and sanitize before acting on it.
Tool execution errors should be handled gracefully; never expose stack traces to clients.
Resource URIs should be validated to prevent directory traversal attacks.
Prompt templates should sanitize user inputs to prevent injection attacks.
Stdio transport requires proper process lifecycle management.
HTTP transport should implement authentication and rate limiting.
Multi-server configurations require careful handling of server failures.
Tool caching should have appropriate TTLs to prevent stale data.
Be cautious with tools that have external side effects; they may be called unexpectedly by AI models.