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.

The Infinispan CLI also provides a stdio transport bridge that allows local MCP clients to communicate with the server.

1.1. Using the CLI as an MCP stdio transport bridge

The MCP feature is experimental and must be explicitly enabled. Start Infinispan Server with -Dorg.infinispan.feature.mcp=true before using the CLI MCP bridge.

The Infinispan CLI provides a stdio transport bridge that allows MCP clients to communicate with a running Infinispan server. The bridge reads JSON-RPC messages from standard input, forwards them to the server’s MCP endpoint, and writes responses to standard output.

This is the recommended way to connect local MCP clients, such as Claude Desktop, Claude Code, Cursor, or GitHub Copilot, to an Infinispan server.

1.1.1. Prerequisites

  • A running Infinispan server with the MCP feature enabled (see Model Context Protocol Endpoint).

  • The Infinispan CLI installed and available on your system.

1.1.2. CLI command

The mcp command starts the stdio transport bridge. You can specify the server connection as a URL, a bookmark name, or the special value local which connects to http://localhost:11222 without authentication.

Syntax
infinispan-cli mcp <server-url|bookmark|local>
Connecting to a local server without authentication
bin/infinispan-cli mcp local
Connecting to a server with a URL
bin/infinispan-cli mcp http://myuser:mypassword@myserver:11222
Connecting using a saved bookmark
bin/infinispan-cli mcp mybookmark

1.1.3. Configuring MCP clients

MCP clients that support the stdio transport can be configured to use the Infinispan CLI as a bridge. The client launches the CLI process and communicates with it through standard input and output.

Claude Code

Create a .mcp.json file in your project directory:

{
  "mcpServers": {
    "infinispan": {
      "command": "/path/to/infinispan-server/bin/infinispan-cli",
      "args": ["mcp", "local"]
    }
  }
}
Claude Desktop

Add the following to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "infinispan": {
      "command": "/path/to/infinispan-server/bin/infinispan-cli",
      "args": ["mcp", "local"]
    }
  }
}
Cursor

Add the following to your Cursor MCP configuration (.cursor/mcp.json):

{
  "mcpServers": {
    "infinispan": {
      "command": "/path/to/infinispan-server/bin/infinispan-cli",
      "args": ["mcp", "local"]
    }
  }
}
Other MCP clients

Any MCP client that supports the stdio transport can use the Infinispan CLI bridge. Configure the client to launch the CLI with the mcp command and the appropriate connection argument.

1.1.4. Connecting to secured servers

When connecting to a server that requires authentication, provide credentials in the connection URL:

bin/infinispan-cli mcp http://admin:password@myserver:11222

Alternatively, create a bookmark with the bookmark set CLI command and reference it by name:

bin/infinispan-cli bookmark set myserver --url http://myserver:11222 --username admin --password password
bin/infinispan-cli mcp myserver

For servers with TLS, use the --trustall option or configure a truststore through a bookmark.

1.2. MCP Tools

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

1.2.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 - mediaType (string, optional): The media type for the value (for example, text/plain, application/json). Defaults to text/plain

Example:

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

To retrieve an entry from a Protobuf-encoded cache as JSON:

{
  "name": "getCacheEntry",
  "arguments": {
    "cacheName": "people",
    "key": "john",
    "mediaType": "application/json"
  }
}
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 - mediaType (string, optional): The media type for the value (for example, text/plain, application/json). Defaults to text/plain

Example:

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

To store a typed entry in a Protobuf-encoded cache:

{
  "name": "setCacheEntry",
  "arguments": {
    "cacheName": "people",
    "key": "john",
    "value": "{\"_type\":\"Person\",\"name\":\"John Doe\",\"age\":35,\"city\":\"London\"}",
    "mediaType": "application/json"
  }
}
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": {}
}
registerSchema

Registers or updates a Protobuf schema. The .proto extension is appended automatically if not provided.

Description: Runtime data modification: registers or updates a Protobuf schema

Parameters: - schemaName (string, required): The schema name (for example, person.proto) - schema (string, required): The Protobuf schema content

Example:

{
  "name": "registerSchema",
  "arguments": {
    "schemaName": "person.proto",
    "schema": "message Person {\n  required string name = 1;\n  optional int32 age = 2;\n}"
  }
}
Cache Introspection
getCacheConfiguration

Retrieves the full configuration of a cache in JSON format.

Description: Runtime data retrieval: retrieves the configuration of a cache in JSON format

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

Example:

{
  "name": "getCacheConfiguration",
  "arguments": {
    "cacheName": "myCache"
  }
}
getCacheStats

Retrieves statistics for a cache, including hits, misses, evictions, stores, timings, and memory usage.

Statistics must be enabled in the cache configuration for this tool to return meaningful values.

Description: Runtime data retrieval: retrieves statistics for a cache

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

Example:

{
  "name": "getCacheStats",
  "arguments": {
    "cacheName": "myCache"
  }
}
Cluster Operations
getClusterInfo

Retrieves cluster information including members, coordinator, status, rebalancing state, and sites.

Description: Runtime data retrieval: retrieves cluster information

Input Schema: No parameters required

Example:

{
  "name": "getClusterInfo",
  "arguments": {}
}
Counter Operations
createCounter

Creates a counter.

Description: Runtime data modification: creates a counter

Parameters: - counterName (string, required): The name of the counter - type (string, required): The counter type: WEAK, UNBOUNDED_STRONG, or BOUNDED_STRONG - initialValue (number, optional): The initial value. Defaults to zero - storage (string, optional): The storage mode: VOLATILE (default, lost on restart) or PERSISTENT (survives restart) - upperBound (number, optional): The upper bound (inclusive). Only for BOUNDED_STRONG counters - lowerBound (number, optional): The lower bound (inclusive). Only for BOUNDED_STRONG counters

Example:

{
  "name": "createCounter",
  "arguments": {
    "counterName": "pageViews",
    "type": "UNBOUNDED_STRONG",
    "initialValue": 0,
    "storage": "PERSISTENT"
  }
}

To create a bounded counter:

{
  "name": "createCounter",
  "arguments": {
    "counterName": "capacity",
    "type": "BOUNDED_STRONG",
    "initialValue": 50,
    "lowerBound": 0,
    "upperBound": 100
  }
}
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"
  }
}
JVM Diagnostics
getJvmMemory

Retrieves heap and non-heap memory usage, garbage collector statistics, and memory pool details.

Description: JVM diagnostics: retrieves heap/non-heap memory usage, garbage collector stats, and memory pool details

Input Schema: No parameters required

Response Fields: - heap: used, committed, and max memory in megabytes, plus usage percentage - non_heap: used and committed memory in megabytes - garbage_collectors: name, collection count, and collection time for each GC - memory_pools: name, type, used, and max memory for each pool

Example:

{
  "name": "getJvmMemory",
  "arguments": {}
}
getJvmThreads

Retrieves thread counts, peak threads, deadlock detection, and optionally a full thread dump.

Description: JVM diagnostics: retrieves thread counts, peak threads, deadlock detection, and optionally a full thread dump

Parameters: - threadDump (boolean, optional): Whether to include a full thread dump. Defaults to false. The thread dump can be large.

Response Fields: - thread_count: current number of live threads - peak_thread_count: peak live thread count since JVM start - daemon_thread_count: current number of daemon threads - total_started_thread_count: total threads started since JVM start - deadlocked_threads: number of deadlocked threads (zero means no deadlocks) - deadlock_details: details of deadlocked threads if any are detected - thread_dump: full thread dump, included only when threadDump is true

Example:

{
  "name": "getJvmThreads",
  "arguments": {}
}

To include a full thread dump:

{
  "name": "getJvmThreads",
  "arguments": {
    "threadDump": true
  }
}
getJvmInfo

Retrieves JVM version, uptime, input arguments, available processors, and operating system information.

Description: JVM diagnostics: retrieves JVM version, uptime, input arguments, available processors, and OS info

Input Schema: No parameters required

Response Fields: - jvm_name: JVM implementation name - jvm_vendor: JVM vendor - jvm_version: JVM version string - spec_version: Java specification version - uptime_seconds: JVM uptime in seconds - start_time: JVM start time in milliseconds since epoch - input_arguments: list of JVM input arguments (for example, -Xmx512m) - classpath: JVM classpath - os: operating system details including name, version, architecture, available processors, and system load average

Example:

{
  "name": "getJvmInfo",
  "arguments": {}
}

1.3. 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.3.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, that is, 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 is also valuable for security auditing to detect denial-of-service attacks or unusual access patterns.

Example URI:

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

1.3.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.4. MCP Resource Templates

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

1.4.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.5. 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.5.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 (for example, '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 (for example, '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"
  }
}