Integrating Model Context Protocol (MCP) with CAS

Content-Aware Storage (CAS) supports Model Context Protocol (MCP), enabling AI chat applications to access and search vector stores through natural language interactions.

Model Context Protocol (MCP)

Model Context Protocol (MCP) is a standardized JSON-RPC 2.0 protocol that allows AI assistants and chat applications to interact with external services. MCP enables AI clients to discover available capabilities and use them through conversational interfaces.
Benefits of MCP server
  • AI assistants can discover and use CAS vector stores automatically.
  • It supports natural language queries for vector search operations.
  • It provides both standard and streaming response options.

Available MCP tools

CAS uses two primary tools through the MCP interface for working with vector stores.

list_vector_stores
  • Description: Lists all vector stores available in the CAS instance. This tool retrieves the complete inventory of vector stores that can be accessed for search operations.
  • Parameters: The parameters (server_url and auth_token) are needed as input for the CAS server you want to search in.
    Parameter Type Description
    server_url string Required. Base URL of the CAS server (for example, https://<console-ibm-spectrum-fusion-ns.apps.openshifturl>).
    auth_token string Required. Authentication token for API access.
  • Usage example: An AI assistant calls this tool to discover which vector stores are available before performing searches.
search_vector_stores
  • Description: Performs semantic search within a specified vector store. This tool uses vector embeddings to find content similar to the provided query text that returns ranked results based on semantic similarity.
  • Parameters:
    Parameter Type Description
    server_url string Required. Base URL of the CAS server (for example, https://<console-ibm-spectrum-fusion-ns.apps.openshifturl>).
    auth_token string Required. Authentication token for API access.
    vector_store_id string Required. ID of the vector store to search.
    query string Required. Search query text.
    limit integer Optional. Maximum number of results to return. The default value is '10'.
  • Usage example: To find documents about 'machine learning best practices' in a vector store named 'technical_docs', the AI assistant calls this tool with the query text and store ID. The tool returns semantically similar documents that are ranked by relevance score.
get_vector_store_file_content
  • Description: Retrieves the complete content of a specific file from a vector store. Use this tool when you need the complete document after finding it through search results. The file_id can be obtained from search_vector_stores results.
  • Parameters:
    Parameter Type Description
    server_url string Required. Base URL of the CAS server (for example, https://<console-ibm-spectrum-fusion-ns.apps.openshifturl>).
    auth_token string Required. Authentication token for API access.
    vector_store_id string Required. ID of the vector store to search.
    file_id string Required. The ID of the file to fetch content for.
  • Usage example: After searching for storage configuration and finding relevant results, use this tool with the file_id from those results to fetch the complete document content for detailed analysis.
  • Example: Standard MCP endpoint
    curl -k -N -X POST "https://<console-ibm-spectrum-fusion-ns.apps.openshift>/cas/api/v1/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
      "name": "get_vector_store_file_content",
      "arguments": {
        "server_url": "https://<console-ibm-spectrum-fusion-ns.apps.openshifturl>",
        "auth_token": "your_auth_token",
        "vector_store_id": "your_store_id",
        "file_id": "5243905"
      }
    }
  }'
  • Example: MCP streamable endpoint
    curl -k -N -X POST \ https://<console-ibm-spectrum-fusion-ns.apps.openshifturl>/cas/api/v1/mcp-streamable/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
      "name": "get_vector_store_file_content",
      "arguments": {
        "server_url": "https://<console-ibm-spectrum-fusion-ns.apps.openshifturl>",
        "auth_token": "your_auth_token",
        "vector_store_id": "your_store_id",
        "file_id": "5243905"
      }
    }
  }'

Authentication

For more information on authentication, see Content-Aware Storage (CAS) APIs.

All MCP tool calls require authentication. Provide the CAS authentication token in the auth_token parameter when you call any tool. The token is validated by using the same authentication system as the REST APIs.

MCP endpoints

/cas/api/v1/mcp
  • Description: Standard MCP endpoint that provides JSON-RPC 2.0 protocol support for synchronous operations.
  • Method: POST
  • Content-Type: application/json
Initialize example:
curl -X POST \
  https://<console-ibm-spectrum-fusion-ns.apps.openshifturl>/cas/api/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {}
  }'
List available tools:
curl -X POST \
  https://<console-ibm-spectrum-fusion-ns.apps.openshifturl>/cas/api/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'
Call MCP tools:
curl -X POST \
  https://<console-ibm-spectrum-fusion-ns.apps.openshifturl>/cas/api/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "list_vector_stores",
      "arguments": {
        "server_url": "https://<console-ibm-spectrum-fusion-ns.apps.openshifturl>",
        "auth_token": "your_auth_token"
      }
    }
  }'
/cas/api/v1/mcp-streamable/
  • Description: Streaming MCP endpoint that provides real-time response delivery by using Server-Sent Events (SSE). Use this endpoint when continuous or progressive responses are needed.
  • Method: POST
  • Content-Type: application/json
  • Accept: text/event-stream
Initialize example:
curl -N -X POST \
  https://<console-ibm-spectrum-fusion-ns.apps.openshifturl>/cas/api/v1/mcp-streamable/ \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'
Call streaming tools:
curl -k -N -X POST \
https://<console-ibm-spectrum-fusion-ns.apps.openshifturl>/cas/api/v1/mcp-streamable/ \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_vector_stores",
    "arguments": {
      "server_url": "https://<console-ibm-spectrum-fusion-ns.apps.openshifturl>",
      "auth_token": "your-token-here"
    }
  }
}'
curl -N -X POST \
  https://<console-ibm-spectrum-fusion-ns.apps.openshifturl>/cas/api/v1/mcp-streamable/ \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "search_vector_stores",
      "arguments": {
        "server_url": "https://<console-ibm-spectrum-fusion-ns.apps.openshifturl>",
        "auth_token": "your_auth_token",
        "vector_store_id": "your_store_id",
        "query": "your search query",
        "limit": 10
      }
    }
  }'

Getting started using MCP endpoints in your application

To use MCP with CAS, follow these steps:

  1. Obtain the CAS server URL and authentication token.
  2. Configure the AI chat client to connect to the MCP endpoint.

    The AI assistant discovers the available tools automatically.

  3. Begin with using natural language queries that require information from vector stores.

Error handling

MCP follows JSON-RPC 2.0 error conventions. If a request fails, the response includes an error object with a code and message.

Common error codes:

  • -32700: Parse error (invalid JSON)
  • -32600: Invalid request
  • -32601: Method not found
  • -32602: Invalid parameters
  • -32603: Internal error