OpenLink AI Layer (OPAL) MCP Server Setup & Installation Guide

Virtuoso Universal Server Web Application Services
, , , ,
1

Introduction

Prior to the emergence of the Model Context Protocol (MCP), functionality provided by Virtuoso’s OPAL add-on middleware layer was only accessible through the following options:

  1. Webpage widget
  2. Native HTML-based Single Page Application (SPA)
  3. HTTP-based API
  4. CustomGPT from the OpenAI GPT Store

The introduction of MCP provides an open standards–based interface for loosely coupled interactions with the powerful capabilities offered by OPAL. This functionality is packaged as a collection of tools that support the following operations:

  1. Metadata for deductive interactions with relational tables
  2. Metadata for deductive interactions with entity relationship graphs
  3. Query execution (both read and write)
  4. Data Space Administration (covering databases, knowledge graphs, and filesystems)
  5. Virtual Database Management (covering remote ODBC-, JDBC-, and HTTP-accessible data sources)
  6. LLM interactions (covering LLMs from OpenAI, Google, Microsoft, X.AI, Anthropic, Meta, and others)
  7. OPAL Assistants interactions (e.g., Data Twingler, Virtuoso Support, RSS & OPML Feeds, ODBC & JDBC Support, etc)
  8. OpenAPI-based Web Services interactions
  9. Attribute-based Access Controls Management

Architecture

Benefits

LLM-based natural language processing has become an essential part of the computing UI/UX stack. This advancement marks the beginning of a new computing era—one powered by loosely coupled AI Agents that operate collaboratively, and in some cases autonomously, on behalf of end-users to enhance productivity.

Previously disparate activities—often complicated by conflicting incentives—will no longer be persistent sources of complexity in software development and usage. Instead, software solutions will increasingly take the form of orchestrated workflows, built from loosely coupled AI Agents described by domain experts and key stakeholders.

Documentation and coding are converging into a unified process, captured in a single, expressive document. The OPAL Server for MCP brings this powerful vision to life by enabling any MCP client to execute a wide range of operations across data spaces—including databases, knowledge graphs, and filesystems—for seamless data access, integration, and management.

Setup and Installation

Prerequisites

Installation

  1. Upgrade your existing Virtuoso instance by obtaining and installing the latest OPAL and Virtuoso Authentication Layer (VAL) packages via the following VADs:

  2. If not already in place, configure a new secure HTTP (HTTPS) /chat/mcp endpoint using one of the following methods:

    2.1. If using Virtuoso’s built-in HTTPS listener, execute the following command via the isql or Conductor interfaces:

          DB.DBA.VHOST_REMOVE (
            lhost=>':443',
            vhost=>'{cname}',  <-- replace {cname} with the actual host name
            lpath=>'/chat/mcp'
      );

      DB.DBA.VHOST_DEFINE (
            lhost=>':443',
            vhost=>'{cname}',  <-- replace {cname} with the actual host name
            lpath=>'/chat/mcp',
            ppath=>'/SOAP/Http',
            is_dav=>0,
            is_brws=>0,
            auth_fn=>'OAI.DBA.CHAT_WS_AUTH',
            soap_user=>'mcp',
            ses_vars=>0,
            opts=>vector ('cors', '*', 'cors_allow_headers', '*', 'cors_restricted', 0),
            is_default_host=>0
      );

    2.2 If using a reverse proxy server for providing secure HTTPS access to Virtuoso, the following rules are required in the proxy configuration file, using ngnix as an example (similar entries required for the proxy server in use):

    location /chat/mcp/ {
proxy_pass http://127.0.0.1:8890;
proxy_set_header  X-Real-IP  $remote_addr;
proxy_set_header  X-Forwarded-For  $proxy_add_x_forwarded_for;
   proxy_set_header  X-Forwarded-Host $host;
   proxy_set_header  X-Forwarded-Port $server_port;
proxy_set_header  X-Forwarded-Proto $scheme;
   proxy_set_header  X-Forwarded-Server $host;
proxy_set_header  Accept-Encoding  "";

proxy_http_version   1.1;
chunked_transfer_encoding  off;
proxy_set_header   Connection '';
proxy_buffering   off;
proxy_cache    off;
proxy_read_timeout   1d;
   }

  3. Update CORS settings for MCP client access, e.g., from http://localhost/*, http://localhost:6274 (for the MCP Inspector), and https://inspect.mcp.garden (for the Remote MCP Inspector) across the following Virtuoso Web Services endpoints:

    • /.well-known
    • /OAuth2
      Note: Click “Finish” and then “Save Changes” for the CORS settings to take effect.

Usage

Connection Credentials

Before making a connection, you have to decide your preferred connection credentials type along the following lines:

Bearer Token, where you obtain an API Key.
OAuth Handshake, where the API key is obtained at runtime.

Bearer Token

You obtain this particular credential via the following steps:

  1. Go to the client registration page of the Virtuoso server that includes the OPAL add-on: https://{CNAME}/oauth/applications.vsp
  2. Generate an API Key.
  3. Copy and save the generated API Key securely.
  4. Paste the API key into the Bearer Token input field presented in the MCP Inspector’s Authentication field.

Client Application Registration

Screenshot 2025-04-17 at 6.40.28 PM
Screenshot 2025-04-17 at 6.40.28 PM900×765 41.2 KB

Client Application Registration & Credentials Generation

Screenshot 2025-04-17 at 6.41.48 PM
Screenshot 2025-04-17 at 6.41.48 PM806×766 49.7 KB

OAuth2 Client Credentials via an OAuth Flow (or Handshake)

This is achieved by leaving the Bearer Token input field empty and simply using the MCP Inspector’s chosen OAuth handshake to obtain the required Access Token.

The screencast below demonstrates an MCP client that supports the Server-Sent Events (SSE) protocol performing the OAuth 2.1 handshake to obtain credentials for interacting with OPAL.

Local MCP Inspector

Start the locally installed inspector by running the following from your command line interface:

npx -y @modelcontextprotocol/inspector

Remote MCP Inspector

  1. Go to: https://inspect.mcp.garden/#tools
  2. Provide the MCP Server’s SSE endpoint URL.
Connecting via Server Sent Events (SSE)

Take note of your Server’s SSE endpoint URL, which is of the form https://{CNAME}/chat/mcp/sse.

  • For the URIBurner endpoint, this would be https://linkeddata.uriburner.com/chat/mcp/sse.
  • For the Demo Server endpoint, this would be https://demo.openlinksw.com/chat/mcp/sse.
Streamable HTTP

Take note of your Server’s Streamable HTTP endpoint URL, which is of the form https://{CNAME}/chat/mcp/messages.

  • For the URIBurner endpoint, this would be https://linkeddata.uriburner.com/chat/mcp/messages.
  • For the Demo Server endpoint, this would be https://demo.openlinksw.com/chat/mcp/messages.
Screencast Demo – MCP Inspector Usage

Troubleshooting

Connection Issues

As a single-page application, MCP uses browser storage to host connection credentials (e.g., OAuth Client Access and Secrets, as well as Bearer Tokens). As a result, you may need to clean out these credentials from storage when switching across MCP servers.

OPAL MCP Tools Metadata

Tool Name Description Main Functions / Commands Functionality Realm
assistantsConfigurations List available AI Assistant configurations — Assistants
uda_howto AI Assistant for Searching the ODBC/JDBC Drivers HowTo Knowledge Base Similar to vos_howto_search Assistants
vos_howto_search AI Assistant for Searching the Virtuoso HowTo Knowledge Base Keyword-based Assistants
database_backup Database cackup and consistency check check, backup, clear Core DBMS
database_logs Show last N lines of database session logs — Core DBMS
database_scheduler Manage database task scheduler list, add, remove, update Core DBMS
database_schema_objects Retrieve and return a list of all schema names from the connected database. — Core DBMS
database_statistics Obtain DB stats about disk, indexes, space, locks, etc. db_server, disk, index, space, lock, etc. Core DBMS
database_trace Database activity logging Enable/disable by trace_type Core DBMS
execute_spasql_query Execute SPASQL queries (combined SQL or SPARQL syntax handling) SQL/SPARQL prefixed with SPARQL Core DBMS
execute_sql_query Execute SQL queries with default scoped to local Northwind Demo Database SQL with Virtuoso syntax Core DBMS
graphqlQuery Execute GraphQL query for a given URL Needs query, optional url, timeout Core DBMS
chatPromptComplete Large Language Model (LLM) Prompt Handling Prompt completion via bound language model LLM
getModels List bound LLMs Optional filter, provider LLM
val_acl_groups Manage VAL Groups (Basic or Conditional) new, update, delete, list VAL
val_acl_rules Manage Virtuoso Authentication Layer (VAL) Attribute-based Access Controls (ABAC) new, update, delete, list VAL
val_check_in_sandbox Attribute-based Access Control Simulations & Testing via sandbox Needs service_id, mode VAL
database_config_dsn External ODBC DSN Management create, modify, remove, get VDB
database_remote_datasources Remote (External) Data Source Management & Configuration list, link (or attach), unlink, connect, disconnect VDB

Sure! Here’s a Frequently Asked Questions (FAQ) section and a Glossary based on the OpenLink AI Layer (OPAL) MCP Server Setup & Installation Guide.

FAQ

  1. What is OPAL and MCP?
    OPAL is a middleware layer for Virtuoso that enables AI-driven interactions. MCP (Model Context Protocol) provides an open standards-based interface for loosely coupled interactions with OPAL’s capabilities.

  2. What are the benefits of using OPAL with MCP?
    It enables AI-powered automation, improved data access, seamless integration across various databases, knowledge graphs, and filesystems, and enhances productivity by allowing collaborative AI agents.

  3. How do I install and configure the OPAL MCP Server?
    You need a Virtuoso instance with the OPAL add-on installed. Then, configure a secure /chat/mcp endpoint using Virtuoso’s built-in HTTPS listener or a reverse proxy.

  4. What types of authentication are supported?
    OPAL MCP supports authentication via Bearer Tokens (API keys) or an OAuth handshake to obtain credentials at runtime.

  5. What connection methods (transports) are supported by the OPAL MCP Server?
    You can connect via Server-Sent Events (SSE) or Streamable HTTP, depending on the endpoint URL provided.

  6. What tools are published by OPAL’s MCP Server?
    OPAL MCP includes tools for querying data spaces (databases, knowledge bases and graphs, and filesystems), managing authentication layers, data space administration, interacting with AI assistants, and integrating with Large Language Models (LLMs).

Glossary

  • OPAL (OpenLink AI Layer) – Virtuoso add-on middleware layer for creating, deploying, and interacting with AI Agents that are loosely coupled with data spaces (databases, knowledge bases or graphs, and filesystems).
  • MCP (Model Context Protocol) – An open standards-based protocol for AI-assisted interactions with databases and knowledge graphs.
  • Bearer Token – A credential type used for API authentication.
  • OAuth Handshake – Authentication process where credentials are obtained at runtime.
  • SSE (Server-Sent Events) – A method for establishing a continuous connection between a client and server for real-time data exchange.
  • Streamable HTTP – An endpoint format that allows data streaming via HTTP requests.
  • CORS (Cross-Origin Resource Sharing) – Security settings that determine how web applications access resources from different domains, programmatcally e.g., via Javascript-based Single Page Applications.
  • VAL (Virtuoso Authentication Layer) – Virtuoso’s multi-protocol authentication and general security management layer that also includes fine-grained attribute-based access controls (ABAC).

Related