Skip to content

Getting Started

The OpenBI MCP Server is a standard ASP.NET Core 9 web application. You can run it directly with the .NET SDK or as a Docker container.

Prerequisites

Requirement Version Required for
.NET SDK 9.0 or later dotnet run / dotnet publish
Docker any recent version Docker container

Install the .NET 9 SDK: https://dotnet.microsoft.com/download/dotnet/9.0

Option 1 — dotnet run

git clone <repository-url>
cd openbi/OpenBI.MCP.Server

dotnet run

The MCP endpoint is available at:

http://localhost:5000/mcp

Option 2 — Docker

A Dockerfile and docker-compose.yml are provided in the OpenBI/ folder. The compose file sets the build context to the repo root automatically, so all project references resolve correctly.

cd OpenBI
docker compose up

This builds the image and starts the container with all four configuration folders mounted as volumes (resolved relative to OpenBI/OpenBI.MCP.Server/).

The MCP endpoint is available at:

http://localhost:8080/mcp

Secrets volume

The secrets/ volume contains credentials. Never bake secrets into the image — always mount them at runtime and ensure the host path is not committed to source control.

Manual build (advanced)

If you need to build the image without docker compose, run from the repo root: 

docker build -f OpenBI/Dockerfile -t openbi-mcp-server .
Running from any other directory will fail because the Dockerfile references paths relative to the repo root.

First-time setup checklist

Regardless of how you run the server, you need the following before any MCP tool calls will succeed:

  1. Platform definitions — populate platforms/ with at least one platform folder (info.json, visualtypes.json, assetTypes/).
  2. At least one site — create sites/my-site.json (see Configuration).
  3. Secrets — create secrets/my-site.json with credentials for that site.
  4. Connector + converter plugins — publish them into plugins/ (see Plugins).

Build for production (dotnet)

dotnet publish -c Release -o publish/
cd publish/
dotnet OpenBI.MCP.Server.dll

The published output is self-contained: appsettings.json and the sites/, secrets/, and platforms/ folders are all copied alongside the binary.

Installing a plugin

Plugins must be published into the runtime plugins/ directory — either the build output folder (when using dotnet run) or the mounted volume (when using Docker).

dotnet publish MyOrg.Connectors.MyPlatform \
  -c Release \
  -o ./plugins/MyOrg.Connectors.MyPlatform

Build output vs project folder

When using dotnet run, the plugin loader reads AppContext.BaseDirectory at runtime (bin/Debug/net9.0/). Publishing to the project source plugins/ folder has no effect. When using Docker, publish to the path that maps to the /app/plugins volume.

Verifying startup

On a successful start you should see log lines similar to:

[INF] Plugin loaded: MyOrg.Connectors.MyPlatform - 1 type(s) registered
[INF] Plugin loaded: MyOrg.Converters.MyPlatform - 1 type(s) registered
[INF] Site registry: FileSiteRegistry loaded 2 site(s)
[INF] Now listening on: http://localhost:5000

If no sites are configured the server still starts without crashing. Tools that require id_site will return "Unknown or invalid id_site" until at least one site is registered.