Infinispan MCP Server

What You Will Learn

How to start an Infinispan Server with the MCP (Model Context Protocol) endpoint enabled and connect AI assistants such as Claude Code or Claude Desktop using the CLI stdio transport bridge to manage caches, counters, and schemas through natural language.

Prerequisites

Docker Compose or Podman Compose
An MCP client (e.g., Claude Code, Claude Desktop, or an IDE with MCP support)

Step 1: Start the Infinispan Server

Start the Infinispan Server with the MCP endpoint enabled using Docker Compose:

docker compose up -d

The server uses Basic authentication with credentials admin / password.

Tip	You can replace `docker` with `podman` in the command above if you use Podman.

Step 2: Connect an MCP Client

The Infinispan CLI acts as a stdio transport bridge between MCP clients and the server. It reads JSON-RPC messages from standard input, forwards them to the server’s MCP endpoint, and writes responses to standard output.

In this tutorial, the CLI runs inside the Docker container via docker exec.

This folder contains an .mcp.json file pre-configured to connect to the local Infinispan MCP endpoint using the CLI stdio bridge. Copy it to any project where you want MCP access:

cp .mcp.json /path/to/your/project/.mcp.json

You can also add the MCP server manually with the Claude Code CLI:

claude mcp add infinispan -- \
  docker exec -i infinispan-mcp /opt/infinispan/bin/cli.sh mcp http://admin:password@localhost:11222

For Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "infinispan": {
      "command": "docker",
      "args": ["exec", "-i", "infinispan-mcp", "/opt/infinispan/bin/cli.sh", "mcp", "http://admin:password@localhost:11222"]
    }
  }
}

Tip	If you have the Infinispan server distribution installed locally, you can point directly to the CLI binary instead of using `docker exec`. Use `"/path/to/infinispan-server/bin/infinispan-cli"` as the `command` and `["mcp", "http://admin:password@localhost:11222"]` as the `args`.

Using CLI bookmarks

Instead of hardcoding URLs and credentials in your MCP configuration, you can use CLI bookmarks. A bookmark stores the connection details (URL, credentials, TLS settings) under a name that you can reference in the mcp command.

Create a bookmark:

docker exec infinispan-mcp /opt/infinispan/bin/cli.sh bookmark set myserver \
  --url http://localhost:11222 --username admin --password password

Or if you have a local CLI installation:

infinispan-cli bookmark set myserver \
  --url http://localhost:11222 --username admin --password password

Then reference the bookmark name in your .mcp.json:

{
  "mcpServers": {
    "infinispan": {
      "command": "docker",
      "args": ["exec", "-i", "infinispan-mcp", "/opt/infinispan/bin/cli.sh", "mcp", "myserver"]
    }
  }
}

Or with a local CLI installation:

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

Tip	This is especially useful when connecting to production or secured servers, since credentials and TLS settings are stored in the CLI configuration rather than in project files.

Step 3: Interact with Infinispan

Once connected, ask your AI assistant to perform operations such as:

Create a cache called "my-cache"
Put the key "greeting" with value "hello world" in my-cache
Get the value for key "greeting" from my-cache
List all caches
Create a strong counter called "visitor-count"

You can also verify the MCP endpoint directly with curl:

curl http://localhost:11222/rest/v3/mcp \
  -u admin:password \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'

Step 4: Stop the Server

docker compose down

Available MCP Capabilities

The Infinispan MCP server exposes:

Tools: Cache operations (create, list, get, put, remove, query), counter operations (get, increment, decrement), and schema management
Resources: Server information, configuration, and audit/access logs
Prompts: Documentation search guidance

What’s Next

Vector search for kNN similarity queries
LangChain4j integration for building AI applications with Infinispan