Infinispan Server provides a Model Context Protocol (MCP) server implementation that can be easily integrated within AI-driven workflows. Use MCP clients, such as Claude Desktop, to seamlessly access and manipulate data stored in your Infinispan Server. This guide provides details about the features available in Infinispan’s MCP endpoint.

1. Model Context Protocol Endpoint

THE MCP ENDPOINT IS AN EXPERIMENTAL FEATURE AND MUST BE EXPLICITLY ENABLED.

To enable the MCP endpoint, start Infinispan Server with the org.infinispan.feature.mcp system property set to true:

Linux
bin/server.sh -Dorg.infinispan.feature.mcp=true
Windows
bin\server.bat -Dorg.infinispan.feature.mcp=true

Infinispan server’s REST connector exposes an endpoint which implements a Model Context Protocol (MCP) server compliant with the 2025-03-26 Specification using the Streamable HTTP transport.

1.1. MCP Tools

Infinispan’s MCP tools expose operations that allows models to interact with various components, such as caches, counters, configurations and metrics.

1.1.1. Available Tools

Cache Operations
getCacheNames

Retrieves all the available cache names.

Description: Runtime data inventory: retrieves all the available cache names. For server status/health, use log resources instead.

Input Schema: No parameters required

Example:

{
  "name": "getCacheNames",
  "arguments": {}
}
createCache

Creates a new cache with default configuration.

Description: Runtime data modification: creates a cache

Parameters: - cacheName (string, required): The name of the cache

Example:

{
  "name": "createCache",
  "arguments": {
    "cacheName": "myCache"
  }
}
getCacheEntry

Retrieves a value from a cache.

Description: Runtime data retrieval: retrieves a value from a cache

Parameters: - cacheName (string, required): The name of the cache - key (string, required): The key of the entry

Example:

{
  "name": "getCacheEntry",
  "arguments": {
    "cacheName": "myCache",
    "key": "myKey"
  }
}
setCacheEntry

Inserts or updates an entry in a cache.

Description: Runtime data modification: inserts/updates an entry in a cache

Parameters: - cacheName (string, required): The name of the cache - key (string, required): The key of the entry - value (string, required): The value of the entry - lifespan (number, optional): The lifespan of the entry in milliseconds - maxIdle (number, optional): The maximum idle time of the entry in milliseconds

Example:

{
  "name": "setCacheEntry",
  "arguments": {
    "cacheName": "myCache",
    "key": "myKey",
    "value": "myValue",
    "lifespan": 60000,
    "maxIdle": 30000
  }
}
deleteCacheEntry

Deletes an entry from a cache.

Description: Runtime data modification: deletes an entry from a cache

Parameters: - cacheName (string, required): The name of the cache - key (string, required): The key of the entry

Example:

{
  "name": "deleteCacheEntry",
  "arguments": {
    "cacheName": "myCache",
    "key": "myKey"
  }
}
queryCache

Queries a cache using Ickle query language.

Description: Runtime data retrieval: queries a cache using Ickle query language

Parameters: - cacheName (string, required): The name of the cache - query (string, required): The Ickle query

Example:

{
  "name": "queryCache",
  "arguments": {
    "cacheName": "myCache",
    "query": "FROM com.example.Person WHERE age > 18"
  }
}
Schema Operations
getSchemas

Retrieves all the available Protobuf schemas.

Description: Runtime data inventory: retrieves all the available schemas. For server status/health, use log resources instead.

Input Schema: No parameters required

Example:

{
  "name": "getSchemas",
  "arguments": {}
}
Counter Operations
getCounterNames

Retrieves all the available counter names.

Description: Runtime data inventory: retrieves all the available counter names. For server status/health, use log resources instead.

Input Schema: No parameters required

Example:

{
  "name": "getCounterNames",
  "arguments": {}
}
getCounter

Retrieves the value of a counter.

Description: Runtime data retrieval: retrieves the value of a counter

Parameters: - counterName (string, required): The name of the counter

Example:

{
  "name": "getCounter",
  "arguments": {
    "counterName": "myCounter"
  }
}
increment

Increments the value of a counter.

Description: Runtime data modification: increments the value of a counter

Parameters: - counterName (string, required): The name of the counter

Example:

{
  "name": "increment",
  "arguments": {
    "counterName": "myCounter"
  }
}
decrement

Decrements the value of a counter.

Description: Runtime data modification: decrements the value of a counter

Parameters: - counterName (string, required): The name of the counter

Example:

{
  "name": "decrement",
  "arguments": {
    "counterName": "myCounter"
  }
}

1.2. MCP Resources

The Model Context Protocol (MCP) provides a standardized way for servers to expose resources to clients. Resources allow servers to share data that provides context to language models, such as files, database schemas, or application-specific information. Each resource is uniquely identified by a URI.

1.2.1. Available Resources

Infinispan exposes the following predefined resources through the MCP server:

Server Log

URI: infinispan+logs://server?lines=200

Name: server log

MIME Type: text/plain

Description: PRIMARY SOURCE OF INFORMATION FOR SERVER STATUS/HEALTH. Returns info about server status, health, errors, warnings, exceptions, startup/shutdown events, and troubleshooting.

Usage: This resource provides access to the main server log file, which contains comprehensive information about the Infinispan server’s operations, including startup sequences, configuration details, error messages, warnings, and general operational events. It is the primary resource for monitoring server health and troubleshooting issues.

Example URI:

infinispan+logs://server?lines=200
Audit Log

URI: infinispan+logs://audit?lines=200

Name: audit log

MIME Type: text/plain

Description: PRIMARY SOURCE OF INFORMATION FOR SERVER STATUS/SECURITY. Returns info about security events: authentication attempts, authorization failures, suspicious activity.

Usage: This resource provides access to the audit log, which tracks all security-related events on the server. Use this resource to monitor authentication attempts, detect authorization failures, and identify potential security threats or suspicious activities.

Example URI:

infinispan+logs://audit?lines=200
REST Access Log

URI: infinispan+logs://rest-access?lines=200

Name: REST access log

MIME Type: text/plain

Description: PRIMARY SOURCE OF INFORMATION FOR SERVER STATUS/WORKLOAD. Returns info about REST API usage patterns: request rates, errors (4xx/5xx), slow endpoints, client IPs. Useful also for security auditing, i.e. detecting DoS attacks or suspicious activity.

Usage: This resource provides access to the REST API access log, which records all HTTP requests to the Infinispan REST endpoint. Analyze this log to understand API usage patterns, identify performance bottlenecks, detect errors, and monitor client activity. It’s also valuable for security auditing to detect denial-of-service attacks or unusual access patterns.

Example URI:

infinispan+logs://rest-access?lines=200

1.2.2. Resource Parameters

lines Parameter

The lines parameter controls how many lines to retrieve from log resources.

Default: 200

Minimum: 1

Maximum: 10000

Example:

infinispan+logs://server?lines=500

1.3. MCP Resource Templates

Resource templates allow servers to expose parameterized resources using URI templates. Arguments may be auto-completed through the completion API.

1.3.1. Available Resource Templates

Infinispan provides the following resource templates that allow dynamic resource access:

Cache Value Template

URI Template: infinispan+cache://{cacheName}/{key}

Name: cache value

Description: Runtime data information: retrieves a value from a cache

Parameters: - {cacheName}: The name of the cache to access - {key}: The key of the entry to retrieve

Usage: This template allows you to retrieve individual cache entries by constructing a URI with the cache name and key. This provides direct access to cached data through the MCP resource mechanism.

Example URIs:

infinispan+cache://myCache/user123
infinispan+cache://sessionCache/abc-def-ghi
infinispan+cache://productCatalog/product-456
Counter Value Template

URI Template: infinispan+counter://{countername}

Name: counter value

Description: Runtime data information: retrieves a value from a counter

Parameters: - {countername}: The name of the counter to access

Usage: This template allows you to retrieve the current value of a counter by constructing a URI with the counter name. Counters are distributed atomic values used for tracking metrics or coordinating operations across the cluster.

Example URIs:

infinispan+counter://requestCount
infinispan+counter://activeUsers
infinispan+counter://totalTransactions
Server Logs Template

URI Template: infinispan+logs://{logType}?lines={lines}

Name: server logs

MIME Type: text/plain

Description: PRIMARY SOURCE OF INFORMATION FOR SERVER STATUS/HEALTH. Useful to retrieve different types of server logs. Primary source of information to monitor server status, server health, troubleshoot issues, and audit security-related events.

Parameters: - {logType}: The type of log to retrieve. Valid values: * server: Main server log * audit: Security audit log * rest-access: REST API access log * hotrod-access: Hot Rod protocol access log * memcached-access: Memcached protocol access log * resp-access: RESP protocol access log - {lines}: Number of lines to retrieve (default: 200, min: 1, max: 10000)

Usage: This template provides flexible access to various server log files. By specifying the log type and number of lines, you can retrieve exactly the log data you need for monitoring, troubleshooting, or security auditing.

Example URIs:

infinispan+logs://server?lines=500
infinispan+logs://audit?lines=100
infinispan+logs://rest-access?lines=1000
infinispan+logs://hotrod-access?lines=200

1.4. MCP Prompts

The Model Context Protocol (MCP) provides a standardized way for servers to expose prompt templates to clients. Prompts allow servers to provide structured messages and instructions for interacting with language models. Clients can discover available prompts, retrieve their contents, and provide arguments to customize them.

1.4.1. Available Prompts

Infinispan provides the following prompts to help users find relevant documentation:

find-documentation

Helps find relevant Infinispan documentation on the official website for a specific topic.

Name: find-documentation

Description: Helps find relevant Infinispan documentation on the official website for a specific topic. Primary source of information MUST BE https://infinispan.org/documentation

Arguments: - topic (required): What to search for in the documentation (e.g., 'cache configuration', 'Hot Rod client') - context (optional): Additional context about your goal or use case

Usage: This prompt guides the language model to search the official Infinispan documentation for information about a specific topic. When invoked, it provides a structured search request along with a comprehensive list of documentation URLs organized by topic area.

Example:

{
  "name": "find-documentation",
  "arguments": {
    "topic": "cache configuration",
    "context": "I need to configure a distributed cache with persistence"
  }
}

Documentation Areas Covered: The prompt provides direct links to documentation for:

  • Configuring caches

  • Encoding and marshalling data

  • Querying caches

  • Embedded mode

  • Hot Rod Java client

  • REST API

  • RESP (Redis clients)

  • Memcached clients

  • Hibernate ORM cache provider

  • Quarkus integration

  • Spring Boot integration

  • Server administration

  • Operator (Kubernetes/OpenShift)

  • Helm Chart

  • Ansible Collection

  • Command-Line Interface (CLI)

  • Planning and Tuning

  • Cross-site replication

  • Integration with AI/ML frameworks (Quarkus Langchain, Langchain, Langchain4j)

  • Integration with other frameworks (Vert.x, Keycloak, Apache Camel, WildFly)

find-documentation-guided

Helps find relevant Infinispan documentation with topic suggestions for common areas.

Name: find-documentation-guided

Description: Helps find relevant Infinispan documentation with topic suggestions for common areas

Arguments: - topic (required): What to search for in the documentation (e.g., 'cache configuration', 'Hot Rod client') - context (optional): Additional context about your goal or use case

Usage: This is a variation of the find-documentation prompt that provides auto-completion suggestions for common documentation topics. When using MCP clients that support completion, this prompt will offer a list of frequently accessed topic areas to choose from.

Available Topic Completions: - Cache Configuration - Cross-Site Replication - Hot Rod Client - Query API - REST API - Persistence - Security - Clustering - Transactions - Server Management

Example:

{
  "name": "find-documentation-guided",
  "arguments": {
    "topic": "Hot Rod client",
    "context": "Setting up a Java client application"
  }
}