Skip to content

Actian MCP Server for NoSQL

Connect your MCP-compatible client to Actian NoSQL using the Actian MCP Server. Once configured, clients can explore schema metadata, execute read-only JPQL queries, and inspect the full details of retrieved persistent objects.

Capabilities

The Actian NoSQL MCP Server supports the following operations:

Action Description
Discover the Schema List all classes and explore their fields and inheritance hierarchy.
Run JPQL queries Execute read-only queries against your database.
Retrieve objects by ID Fetch one or many objects directly by LOID for the fastest retrieval path.

Prerequisites

Before starting the server, ensure the following requirements are met:

  • Container Engine: Docker installed and running on the host machine.
  • Database credentials: Access details for the Actian NoSQL database.
  • Secure deployment files (Optional): TLS certificate and key files for secure deployments.
  • OIDC provider (Optional): Required if you are using OAuth authentication.

Configuration

All configuration is provided through an application.properties file mounted into the container at /home/jboss/config/application.properties. Environment variables are supported as an alternative — any property can be passed with a -e flag using SCREAMING_SNAKE_CASE notation, and they take precedence over the file.

NoSQL Connection

Property Required Description
nsql.connectionURL Yes Database connection URL in the format database@server:port#user:password. port, user, and password are optional.

Quarkus Properties

The server is a Quarkus application. Any standard Quarkus configuration property can be set in application.properties. Some commonly used properties:

Property Default Description
quarkus.http.port 8080 HTTP listening port.
quarkus.http.ssl-port 8443 HTTPS listening port.

Securing the server

To enable OAuth 2.0 or TLS, additional properties are required. See Authentication for the full configuration reference.

Logging

The root log level is controlled by quarkus.log.level (default: INFO).

Available log levels:

Level Description
OFF A special level used in configuration to turn off logging.
FATAL A critical service failure or total inability to handle any requests.
ERROR A major issue in processing or an inability to complete a request.
WARN A non-critical service error or problem that might not require immediate correction.
INFO Service lifecycle events or other important infrequent information.
DEBUG Additional information about lifecycle events or events not tied to specific requests, useful for debugging.
TRACE Detailed per-request debugging information, potentially at a very high frequency.
ALL A special level to turn on logging for all messages, including custom levels.

Individual categories can be tuned independently using quarkus.log.category."<package>".level. The following Actian-specific categories are available:

Category Description
com.actian All Actian components.
com.actian.mcp MCP protocol layer — primitives, guardrails, and related handling.
com.actian.nsql Actian NoSQL data layer — schema discovery, query execution, and object mapping.

For example, to enable debug logging for the Actian NoSQL data layer:

quarkus.log.category."com.actian.nsql".level=DEBUG

See the Quarkus logging guide for the full reference.

Start the Server

Add settings to application.properties and mount it into the container:

nsql.connectionURL=<connection-url>
docker run \
  -v $(pwd)/application.properties:/home/jboss/config/application.properties:ro \
  -p 8080:8080 \
  actian/nsql-mcp-server:1.0.0

Once the container is running, connect the MCP client to the exposed server endpoint using the host and port from the configuration.


Connect Using a Python Client

Other MCP clients

For connecting AI clients such as Claude Desktop, Cursor, fast-agent, and Codex, see the Connecting MCP Clients guide.

The following example demonstrates how to connect to a running Actian MCP Server for Actian NoSQL using the FastMCP Python client.

Prerequisites

Install the required packages:

pip install fastmcp
pip install httpx  # required for OAuth authentication

Basic Connection Example

"""Actian MCP Server for Actian NoSQL — Python client example."""

import asyncio
import json
from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport


async def main():
    # Replace with your Actian MCP Server URL
    server_url = "http://localhost:8080/mcp"

    transport = StreamableHttpTransport(url=server_url)

    async with Client(transport, timeout=60) as client:

        # 1. Discover available tools and their parameters
        tools = await client.list_tools()
        print("Available tools:")
        for tool in tools:
            print(f"  - {tool.name}")

        # 2. List all classes in the database
        result = await client.call_tool("list_classes", {})
        print(f"\nClasses:\n{json.dumps(result.structured_content, indent=2)}")

        # 3. Describe a specific class
        # Replace "Employee" with a class name from your database
        result = await client.call_tool(
            "describe_class", {"className": "Employee"}
        )
        print(f"\nEmployee class schema:\n{json.dumps(result.structured_content, indent=2)}")

        # 4. Execute a read-only JPQL query
        # Replace class and field names to match your schema
        result = await client.call_tool(
            "execute_query",
            {"jpql": "select e from Employee e"},
        )
        print(f"\nQuery results:\n{json.dumps(result.structured_content, indent=2)}")


if __name__ == "__main__":
    try:
        asyncio.run(main())
    except Exception as e:
        print(f"Error: {e}")

Connect Using OAuth Authentication

When you deploy the server with OAuth enabled over HTTPS, provide authentication and TLS/SSL parameters in the client code

"""Actian MCP Server for Actian NoSQL — Python client with OAuth and TLS."""

import asyncio
import json
import ssl
import httpx
import certifi
from fastmcp import Client
from fastmcp.client.auth import OAuth
from fastmcp.client.transports import StreamableHttpTransport


# Replace with your values
MCP_URL = "https://mcp.example.com:8443/mcp"
CLIENT_ID = "<your-client-id>"    # OAuth 2.0 client ID registered in your identity provider
CALLBACK_PORT = <callback-port>   # must match the redirect URI registered in your identity provider
CA_CERT = "/path/to/server.crt"  # self-signed certificate of the MCP server


def make_httpx_client(**kwargs) -> httpx.AsyncClient:
    """Create an HTTP client that trusts both the identity provider and the MCP server certificate."""
    # Load standard public certificates (for the identity provider)
    ssl_ctx = ssl.create_default_context(cafile=certifi.where())
    # Append the self-signed certificate (for the MCP server)
    ssl_ctx.load_verify_locations(cafile=CA_CERT)
    return httpx.AsyncClient(verify=ssl_ctx, **kwargs)


async def main():
    oauth = OAuth(
        client_id=CLIENT_ID,
        callback_port=CALLBACK_PORT,
        httpx_client_factory=make_httpx_client,  # used for identity provider requests
    )

    transport = StreamableHttpTransport(
        url=MCP_URL,
        auth=oauth,
        httpx_client_factory=make_httpx_client,  # used for MCP server requests
    )

    async with Client(transport, timeout=120) as client:
        tools = await client.list_tools()
        print(f"Connected — {len(tools)} tools available")

        result = await client.call_tool(
            "execute_query",
            {"jpql": "select e from Employee e"},
        )
        print(f"Results:\n{json.dumps(result.structured_content, indent=2)}")


if __name__ == "__main__":
    try:
        asyncio.run(main())
    except Exception as e:
        print(f"Error: {e}")

Tip

The FastMCP OAuth helper automatically handles the browser-based login flow. Ensure you run the client on a machine with a web browser available.


Next Steps

  • Authentication
    Secure the server with OAuth 2.0 and an external identity provider.

  • Tools
    Explore the available MCP tools for NoSQL database operations.

  • Resources
    Learn more about schema metadata resources.

  • Prompts
    Use pre-built prompt templates for common workflows.