Configuration

The OpenBI MCP Server is configured through three layers:

1. appsettings.json — server-level settings (logging, plugin overrides)
2. sites/ — one JSON file per BI platform instance
3. secrets/ — credentials for each site, referenced from the site JSON

---

Plugin architecture overview

The server is built around three extensibility points that work together:

┌─────────────────────────────────────────────────────────────────┐
│                      OpenBI MCP Server                          │
│                                                                 │
│  ┌──────────────────┐   ┌─────────────────┐   ┌─────────────┐  │
│  │   Site Registry  │   │   Connector      │   │  Converter  │  │
│  │  (ISiteRegistry) │   │(ISiteConnection  │   │(IOpenBIConv │  │
│  │                  │   │    Factory)      │   │  erterFact) │  │
│  │  Loads & exposes │   │  Connects to a   │   │  Translates │  │
│  │  site config at  │   │  BI platform     │   │  artifacts  │  │
│  │  startup         │   │  via its API     │   │ ↔ OpenBI    │  │
│  └──────────────────┘   └─────────────────┘   └─────────────┘  │
│                                                                 │
│  All three are resolved from plugins/ at startup                │
└─────────────────────────────────────────────────────────────────┘

Site Registry

The Site Registry is responsible for loading and exposing the list of BI platform instances (sites) to the server. By default, the built-in FileSiteRegistry is used — it scans the sites/ folder and loads every .json file it finds. Each file describes one site.

A custom ISiteRegistry implementation can be loaded from a plugin (e.g. a registry that fetches site configuration from a remote API or database). See Plugins for details.

Connectors

A Connector (ISiteConnectionFactory) establishes a live connection to a BI platform — authenticating, querying the asset catalog, downloading artifact bytes, and uploading converted artifacts. Connectors are loaded from plugins and referenced per-site in the site JSON.

Converters

A Converter (IOpenBIConverterFactory) translates between the BI platform's native artifact format and the OpenBI domain model. Converters are loaded from plugins and referenced per-site in the site JSON.

---

Platforms folder

The platforms/ directory describes the BI platforms that the server knows about. Each platform has its own subfolder:

platforms/
└── my-platform/
    ├── info.json             ← platform identity
    ├── visualtypes.json      ← visual type catalog (for create_visual / projections)
    └── assetTypes/
        ├── Report.md         ← agent authoring instructions for Report assets
        └── DataModel.md      ← agent authoring instructions for DataModel assets

info.json

{
  "id": "my-platform",
  "name": "My BI Platform"
}

The id field is used as idPlatform in site JSON files and as the platform_id parameter in MCP discovery tools.

visualtypes.json

A JSON array describing every visual type supported by the platform, including the projection roles (data bindings) each visual accepts. This is returned by the list_bi_platform_visual_types tool and consumed by AI agents when building report visuals.

assetTypes/

Each Markdown file in this folder is one asset type (e.g. Report.md, SemanticModel.md). The filename stem becomes the asset_type_id. The content is a set of rules and a step-by-step execution policy that the AI agent reads before authoring that type of asset (get_bi_platform_asset_type_instructions tool).

---

Sites folder

The sites/ folder is scanned at startup by the FileSiteRegistry. Each .json file is one site — a specific instance of a BI platform (e.g. a production server, a development server of the same platform).

Site JSON schema

{
  "idSite": "my-bi-site",
  "siteName": "My BI Platform Production",
  "idPlatform": "my-platform",
  "platformName": "My BI Platform",
  "platformSecretsPath": "secrets/my-bi-site.json",
  "siteConnectionFactoryName": "MyOrg.Connectors.MyPlatform.MyConnectionFactory, MyOrg.Connectors.MyPlatform",
  "siteConverterFactoryName": "MyOrg.Converters.MyPlatform.MyConverterFactory, MyOrg.Converters.MyPlatform"
}

Field	Required	Description
idSite	✅	Unique site identifier used by all MCP tool calls (id_site parameter)
siteName	✅	Human-readable display name
idPlatform	✅	Platform identifier — must match the id in platforms/{folder}/info.json
platformName	—	Display name of the platform (informational only)
platformSecretsPath	—	Relative path to the secrets file containing credentials for this site
siteConnectionFactoryName	—	Assembly-qualified name of the connector factory plugin type. Required for query_site_assets, get_folders, download_asset, upload_asset.
siteConverterFactoryName	—	Assembly-qualified name of the converter factory plugin type. Required for download_asset and upload_asset.

Multiple sites can use the same idPlatform with different credentials (e.g. a dev and a production instance of the same platform):

sites/
├── my-platform-dev.json     ← idSite: "my-platform-dev"
└── my-platform-prod.json    ← idSite: "my-platform-prod"

---

Secrets folder

Secrets files contain the credentials and connection parameters for a site. They are referenced via platformSecretsPath in the site JSON. The format is a flat JSON object — keys are platform-specific and defined by the connector plugin.

{
  "key1": "value1",
  "key2": "value2"
}

Do not commit secrets

Add secrets/*.json to .gitignore. For production, use a custom ISecretsVaultRepository plugin that reads from a proper vault (Azure Key Vault, HashiCorp Vault, etc.) instead of the built-in file-based vault.

---

appsettings.json reference

{
  "SiteRegistry": {
    "ImplementationType": ""
  },
  "SecretsVault": {
    "ImplementationType": "",
    "BaseDirectory": ""
  },
  "Serilog": {
    "Using": [ "Serilog.Sinks.Console" ],
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "Microsoft.AspNetCore": "Warning",
        "Microsoft.EntityFrameworkCore": "Warning"
      }
    },
    "WriteTo": [
      {
        "Name": "Console",
        "Args": {
          "outputTemplate": "[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj}{NewLine}{Exception}"
        }
      }
    ]
  }
}

SiteRegistry

Key	Default	Description
ImplementationType	"" (empty)	Assembly-qualified type name of a custom ISiteRegistry plugin. Leave empty to use the built-in FileSiteRegistry (reads sites/*.json).

SecretsVault

Key	Default	Description
ImplementationType	"" (empty)	Assembly-qualified type name of a custom ISecretsVaultRepository plugin. Leave empty to use the built-in JsonFileSecretsVaultRepository (reads secrets/*.json).
BaseDirectory	"" (empty)	Override the base directory for the secrets vault. Defaults to secrets/ relative to the application base directory.

Production overrides

Use appsettings.Production.json or environment variables to override plugin types in production without modifying the base config:

{
  "SiteRegistry": {
    "ImplementationType": "MyOrg.Registry.MyCustomSiteRegistry, MyOrg.Registry"
  }
}

Logging

Configured via standard Serilog settings. The default sink is the console. Add file or remote sinks by referencing additional Serilog packages and adding them under WriteTo.