Benefits

• Universal Accessibility: Exposes OPAL functionality to any application or LLM that understands the OpenAI specification.
• Enhanced Security: Implements robust, attribute-based access controls (ABAC) to ensure data privacy and security at a granular level.
• Simplified Integration: Offers a standardized API that simplifies the process of integrating OPAL's capabilities into new and existing workflows.
• Future-Proof: Aligns with modern development practices and the growing ecosystem of AI tools and services.

Capabilities

The OPAL MCP Server provides API access to a wide range of OPAL's core functionalities, including:

• Database Operations: Execute SQL queries, manage tables, and retrieve metadata.
• Graph Operations: Interact with graph data, manage named graphs, and perform complex graph-based queries.
• LLM Management: Register, bind, and manage Large Language Models for use within the OPAL ecosystem.
• Administrative Tasks: Perform database administration, manage user access, and configure system settings.
• AI-Powered Data Interaction: Leverage advanced features like promptComplete and chatPromptComplete for sophisticated, context-aware data interactions.

Prerequisites

• MCP Experience: Administrative and operational familiarity with MCP setup and use, including experience with our MCP servers for ODBC, JDBC, pyODBC, ADO.NET, or SQLAlchemy.
• OPAL Installation: You must already have an installed and configured OPAL add-on for your Virtuoso instance before proceeding to configure MCP support via this MCP Server.

Setup and Installation

Setting up the OPAL MCP Server involves installing the necessary Virtuoso components and configuring them to work together. Follow these detailed steps:

Installation Steps

1. Install Virtuoso: Download and install the latest on-premise Virtuoso installer for your platform:
   • macOS
   • Windows
   • Linux
   • Linux Nexus Repository

   You can download the latest version from the official Virtuoso website.

2. Install Required VAD Packages: Install the VAL and personal-assistant VADs via the Conductor or iSQL interfaces. These packages provide the core functionality needed for OPAL MCP Server operations.
3. Access the Chat Interface: Navigate to your OPAL instance:
   • Local: https://localhost/chat
   • Remote: https://{CNAME}/chat
4. Initial Login and LLM Setup: Log in with the default dba username. When prompted, enter your preferred Large Language Model (LLM) provider's API key to complete the initial setup.

Additional Components

Once your OPAL instance is up and running, you can optionally install additional components using the Virtuoso Application Distribution (VAD) installer — available via the Virtuoso Conductor UI or the isql command-line tool.

Important VAD Package Examples

These VAD packages significantly expand your OPAL instance's capabilities — enabling advanced data workflows driven by entity relationship types defined in ontologies and enhanced through loosely coupled LLM integrations.

Supported LLMs

Any LLM that provides an API compatible with the OpenAPI specification can be registered and used with the OPAL. This includes popular models from providers like:

• OpenAI — GPT family
• Google — Gemini and Gemma families
• Anthropic — Claude family
• Microsoft — GPT, Grok, and Phi families
• Perplexity — Sonar
• xAI — Grok family
• Mistral — Mistral family
• Alibaba — Qwen family
• DeepSeek — DeepSeek R family
• Meta — Llama family (via Groq or Cerebras)

Attribute-based Access Controls (ABAC)

At this point, you need to secure your OPAL and LLM integrated environment by using fine-grained access controls to determine who is allowed to log into your assistant and under what constraints (restrictions). You achieve this by executing the following commands (using the Conductor or ISQL command-line interfaces) that set up these powerful access controls.

Fine-grained access controls use entity relationship graphs comprising relationships, authorizations, restrictions, groups, and agents (people or bots) that are named unambiguously using standardized identifiers (e.g., Internationalized Resource Identifiers [IRIs]) with terms from ontologies such as:

• W3C's Access Control Ontology
• OpenLink Software's Access Control Ontology
• OpenLink Software's Restrictions Ontology
• Friend Of A Friend [FOAF] Ontology

Create Login Authorization for OPAL via /chat endpoint

OPAL is denoted by the system identifier urn:oai:chat, which makes it possible to construct an authorization for logins that belong to a designated group or list of users. In this case, we simply want to set the authorization scope to the DBA user denoted by the identifier http://localhost/dataspace/person/dba#this as follows:

PREFIX acl: <http://www.w3.org/ns/auth/acl#>
PREFIX oplacl: <http://www.openlinksw.com/ontology/acl#>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
PREFIX oplres: <http://www.openlinksw.com/ontology/restrictions#>

WITH <urn:virtuoso:val:default:rules>
DELETE {
  <#rulePublicChat> ?p ?o .
} WHERE {
  <#rulePublicChat> a acl:Authorization ; ?p ?o .
}
INSERT {
  <#rulePublicChat> a acl:Authorization ;
            foaf:maker <#dba> ;
            oplacl:hasAccessMode oplacl:Read, oplacl:Write ;
            acl:accessTo <urn:oai:chat> ;
            acl:agent <http://localhost/dataspace/person/dba#this> ;
            oplacl:hasRealm oplacl:DefaultRealm ;
            oplacl:hasScope oplacl:Query .
} ;

Create Login Authorization for OPAL via /assist-metal endpoint

If you want to extend the login access to OPAL's Assistants functionality via its /assist-metal endpoint, then execute the following to create a restriction on urn:oai:assistants (which is how this functionality realm is denoted):

PREFIX    acl: <http://www.w3.org/ns/auth/acl#>
PREFIX   foaf: <http://xmlns.com/foaf/0.1/>
PREFIX oplacl: <http://www.openlinksw.com/ontology/acl#>
PREFIX oplres: <http://www.openlinksw.com/ontology/restrictions#>

WITH <urn:virtuoso:val:default:rules>
INSERT
{
  <#assistantsAdmin> a acl:Authorization ;
                    foaf:maker <#dba> ;
                    oplacl:hasAccessMode oplacl:Read, oplacl:Write ;
                    acl:accessTo <urn:oai:assistants> ;
                    acl:agent <http://localhost/dataspace/person/dba#this> ;
                    oplacl:hasRealm oplacl:DefaultRealm ;
                    oplacl:hasScope oplacl:Query .
} ;

System-wide LLM API Key Registration

Rather than repetitively entering LLM API Keys when you log in, it might be preferred to have those keys registered system-wide. To achieve this goal, you need to create a restriction for successfully logged-in users by executing the following:

PREFIX acl: <http://www.w3.org/ns/auth/acl#>
PREFIX oplacl: <http://www.openlinksw.com/ontology/acl#>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
PREFIX oplres: <http://www.openlinksw.com/ontology/restrictions#>

WITH <urn:virtuoso:val:default:restrictions>
DELETE { 
          ?s ?p ?o .
} 
WHERE {
        ?s a oplres:Restriction ;
          oplres:hasRestrictedResource <urn:oai:chat> ; ?p ?o .
        FILTER(?s = <#restrictionAuthChatKey>)
}
INSERT {
            <#restrictionAuthChatKey> a oplres:Restriction ;
                foaf:maker <#dba> ;
                rdfs:label "Allow Api Key" ;
                oplres:hasRestrictedResource <urn:oai:chat> ;
                oplres:hasRestrictedParameter <urn:oai:chat:enable-api-keys> ;
                oplres:hasRealm oplacl:DefaultRealm ;
                oplres:hasAgent <http://localhost/dataspace/person/dba#this> ; ### list of NetIds to have access for system key
                oplres:hasRestrictedValue "true"^^xsd:boolean .
} ;

Large Language Models Registration & Use

With your OPAL instance successfully initialized, you can now bind it to one or more LLMs from the supported list. You achieve this via the following commands executed via the Conductor or iSQL interfaces.

Listing Bound LLMs

Command Syntax:

OAI.DBA.FILL_CHAT_MODELS('{Api Key}', '{llm-vendor-tag}');

Where llm-vendor-tags are: alibaba, claude, deepseek, gemini, groq, mistral, openai, xai.

Usage Examples:

OAI.DBA.FILL_CHAT_MODELS('sk-xxxx', 'openai');
OAI.DBA.FILL_CHAT_MODELS('sk-ant-xxx', 'claude');

Google DeepMind's Gemini does not currently offer an API for LLM listing, so you use:

OAI.DBA.REGISTER_CHAT_MODEL('{llm-vendor-tag}','{llm-name}');

Usage Example:

OAI.DBA.REGISTER_CHAT_MODEL('gemini','gemini-2.5-flash-preview-05-20');

You can view the effects of this command via the Bound LLMs endpoint at: https://{CNAME}/chat/admin/models.vsp

System-Wide LLM API Key Registration

To negate the need to present API Keys for bound LLMs at login time, you can register the API Keys for your chosen LLMs via the following command using the Conductor or ISQL command line interfaces:

Command Syntax:

OAI.DBA.SET_PROVIDER_KEY( '{llm-vendor-tag}', 'api-key')

Usage Examples:

OAI.DBA.SET_PROVIDER_KEY('openai','sk-svcacct-xxx');
OAI.DBA.SET_PROVIDER_KEY('claude','sk-ant-api03-xxx');
OAI.DBA.SET_PROVIDER_KEY('gemini','AIxxxx');

Application Programming Interface (API) Access

Your OPAL instance is also API-accessible, providing functionality for issuing and revoking credentials in the form of:

• Dynamically negotiated OAuth access tokens
• Issued OAuth Credentials and Bearer Tokens

You obtain credentials using the https://{CNAME}/oauth/applications.vsp endpoint, which presents you with the following:

Client Applications Landing Page

Credentials Issue Pages

Once your credentials have been generated and copied to a safe location, you are ready for API-based interaction with your instance using protocols such as the Model Context Protocol (MCP) and the Agent-2-Agent (A2A) Protocol.

Model Context Protocol (MCP) Usage

OPAL includes built-in support for the MCP protocol as both a client and a server, supporting the Server Sent Events (SSE) and Streamable HTTP transport options. This protocol offers direct access to AI Agents/Assistants created using natural language via Markdown with native stored procedures or external OpenAPI-accessible web services as the underlying tooling for executing operations.

To enable use of this protocol, you will need to set up CORS access for your MCP client regarding the following virtual directories via the Conductor UI:

• /.well-known
• /OAuth2

Here's a screenshot sequence depicting how this task is performed for the /OAuth2 virtual directory.

HTTP Server's Virtual Domains

Virtual Directories Listing for the HTTPS Virtual Domain

CORS Accepted Client Origins Listing

MCP Server Endpoints

The following endpoints are automatically generated for your OPAL instance:

• https://{CNAME}/chat/mcp/messages – for the Streamable HTTP transport
• https://{CNAME}/chat/mcp/sse – for the Server Sent Events transport

Claude Desktop Configuration

Here's the JSON-based MCP Server configuration template for Claude Desktop:

{
    "mcpServers": {
        "{Your-Designated-MCP-Server-Name-For-SSE}": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://{CNAME}/chat/mcp/sse"
            ]
        },
        "{Your-Designated-MCP-Server-Name-For-Streamable-HTTP}": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://{CNAME}/chat/mcp/messages"
            ]
        }
    }
}

Claude Desktop Screencast Demo

MCP Inspector

By default, your AWS hosted OPAL instance uses an HTTPS configuration based on a self-signed certificate generated by Virtuoso. As a result, you need to set the following environment variable before starting your MCP inspector sessions:

export NODE_TLS_REJECT_UNAUTHORIZED=0

Naturally, if you reconfigure your instance to use your CA-signed certificate or leverage Virtuoso's native support for the ACME protocol, you can work around this MCP inspector interaction limitation.

Your OPAL instance as an MCP Client

As an MCP client, OPAL is able to bind to tools published by any MCP Server that provides a Streamable HTTP endpoint. For example, our public endpoints:

• https://demo.openlinksw.com/chat/mcp/messages
• https://linkeddata.uriburner.com/chat/mcp/messages

You can test this capability using our public MCP endpoints via the following steps:

1. Obtain Access Credentials in the form of an API Key
2. Go to the following endpoint for your AWS instance: https://{CNAME}/chat/admin/
3. Click on the "Application Authentication" button, which presents an authentication dialog from which you can select the "API Key" tab for registering the API Key obtained in step 1
4. Authenticate, and if successful you will be presented with a list of tools from the remote MCP server.
5. Select a Tool of interest from the MCP Server e.g., execute_sql_query and then expand by clicking on the expand control to interact with the SQL capture interface.

Other MCP Interaction Options

The following MCP Servers also offer bridge-based access to your OPAL instance, courtesy of the stdio transport leveraging data access protocols:

• OpenLink Generic MCP Server for ODBC (for JavaScript/TypeScript runtimes like Node.js)
• OpenLink Generic MCP Server for JDBC (for Java runtimes)
• OpenLink Generic MCP Server for pyODBC (for Python runtimes)
• OpenLink Virtuoso MCP Server for ADO.NET (for .NET runtimes)

FAQ

Glossary

MCP (Model Context Protocol)

An open protocol for securely connecting Large Language Models (LLMs) with application servers and data sources.

OPAL (OpenLink AI Layer)

A middleware layer that provides powerful data integration and virtualization capabilities.

ABAC (Attribute-Based Access Control)

A flexible and granular access control model that defines policies based on attributes of the user, data, and context.

VAD (Virtuoso Application Distribution)

A package format for distributing and installing applications and modules within the Virtuoso platform.