# Bonnard

> Open-source agentic schema for reliable data outputs. Query data through MCP and via our SDK. Create apps, embed data or just simply explore through your preferred agent.

- **Type:** MCP server
- **Install:** `agentstack add mcp-bonnard-data-bonnard`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bonnard-data](https://agentstack.voostack.com/s/bonnard-data)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [bonnard-data](https://github.com/bonnard-data)
- **Source:** https://github.com/bonnard-data/bonnard
- **Website:** https://bonnard.dev

## Install

```sh
agentstack add mcp-bonnard-data-bonnard
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Self-hosted semantic layer for AI agents.

  
  
  

  Docs ·
  CLI ·
  Discord ·
  Website

---

Bonnard is an agent-native semantic layer — one set of metric definitions, every consumer (AI agents, apps, dashboards) gets the same governed answer. This repo is the self-hosted Docker deployment: run Bonnard on your own infrastructure with no cloud account needed.

## Quick Start

```bash
# 1. Scaffold project
npx @bonnard/cli init --self-hosted

# 2. Configure your data source
#    Edit .env with your database credentials

# 3. Start the server
docker compose up -d

# 4. Define your semantic layer
#    Add cube/view YAML files to bonnard/cubes/ and bonnard/views/

# 5. Deploy models to the server
bon deploy

# 6. Verify your semantic layer
bon schema

# 7. Connect AI agents
bon mcp
```

Requires [Node.js 20+](https://nodejs.org) and [Docker](https://docs.docker.com/engine/install/).

## What's Included

- **MCP server** — AI agents query your semantic layer over the [Model Context Protocol](https://docs.bonnard.dev/docs/mcp)
- **Cube semantic layer** — SQL-based metric definitions with caching, access control, and multi-database support
- **Cube Store** — pre-aggregation cache for fast analytical queries
- **Admin UI** — browse deployed models, views, and measures at `http://localhost:3000`
- **Deploy API** — push model updates via `bon deploy` without restarting containers
- **Health endpoint** — `GET /health` for uptime monitoring

## Connecting AI Agents

Run `bon mcp` to see connection config for your setup. Examples below.

### Claude Desktop / Cursor

```json
{
  "mcpServers": {
    "bonnard": {
      "url": "https://bonnard.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-token-here"
      }
    }
  }
}
```

### Claude Code

```json
{
  "mcpServers": {
    "bonnard": {
      "type": "url",
      "url": "https://bonnard.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-token-here"
      }
    }
  }
}
```

### CrewAI (Python)

```python
from crewai import MCPServerAdapter

mcp = MCPServerAdapter(
    url="https://bonnard.example.com/mcp",
    transport="streamable-http",
    headers={"Authorization": "Bearer your-secret-token-here"}
)
```

## Production Deployment

### Authentication

Protect your endpoints by setting `ADMIN_TOKEN` in `.env`:

```env
ADMIN_TOKEN=your-secret-token-here
```

All API and MCP endpoints will require `Authorization: Bearer `. The `/health` endpoint remains open for monitoring.

Restart after changing `.env`:

```bash
docker compose up -d
```

### TLS with Caddy

[Caddy](https://caddyserver.com) provides automatic HTTPS via Let's Encrypt.

Create a `Caddyfile` next to your `docker-compose.yml`:

```
bonnard.example.com {
    reverse_proxy localhost:3000
}
```

Add Caddy to your `docker-compose.yml`:

```yaml
  caddy:
    image: caddy:2
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
    restart: unless-stopped
```

Add the volume at the top level:

```yaml
volumes:
  models: {}
  caddy_data: {}
```

Then remove the Bonnard port mapping (`ports: - "3000:3000"`) since Caddy handles external traffic.

### Deploy to a VM

```bash
# Copy project files to your server
scp -r . user@your-server:~/bonnard/

# SSH in and start
ssh user@your-server
cd ~/bonnard
docker compose up -d
```

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `CUBEJS_DB_TYPE` | Database driver (`postgres`, `duckdb`, `snowflake`, `bigquery`, `databricks`, `redshift`, `clickhouse`) | `duckdb` |
| `CUBEJS_DB_*` | Database connection settings (host, port, name, user, pass) | — |
| `CUBEJS_DATASOURCES` | Comma-separated list for multi-datasource setups | `default` |
| `CUBEJS_API_SECRET` | HS256 secret for Cube JWT auth (auto-generated by `bon init`) | — |
| `ADMIN_TOKEN` | Bearer token for API/MCP authentication | — (open) |
| `CUBE_PORT` | Cube API port | `4000` |
| `BONNARD_PORT` | Bonnard server port | `3000` |
| `CORS_ORIGIN` | Allowed CORS origins | `*` |
| `CUBE_VERSION` | Cube Docker image tag | `v1.6` |
| `BONNARD_VERSION` | Bonnard Docker image tag | `latest` |

See `.env.example` for a full annotated configuration file.

## Architecture

| Service | Image | Role |
|---------|-------|------|
| `cube` | `cubejs/cube` | Semantic layer engine — executes queries against your warehouse |
| `cubestore` | `cubejs/cubestore` | Pre-aggregation cache — stores materialized results for fast reads |
| `bonnard` | `ghcr.io/bonnard-data/bonnard` | MCP server, admin UI, deploy API — the interface layer for agents and tools |

All three services communicate over an internal Docker network. Only `bonnard` (port 3000) and optionally `cube` (port 4000) are exposed externally.

## Monitoring

```bash
# Health check
curl http://localhost:3000/health

# View logs
docker compose logs -f

# View active MCP sessions
curl -H "Authorization: Bearer " http://localhost:3000/api/mcp/sessions
```

## Deploying Schema Updates

From your development machine:

```bash
bon deploy
```

This pushes your cube/view YAML files to the running server. No restart needed — Cube picks up changes automatically.

## Pinning Versions

Control image versions via `.env`:

```env
CUBE_VERSION=v1.6
BONNARD_VERSION=latest
```

## Supported Data Sources

**Warehouses:** Snowflake, Google BigQuery, Databricks, PostgreSQL (including Supabase, Neon, RDS), Amazon Redshift, DuckDB (including MotherDuck), ClickHouse

See the [full documentation](https://docs.bonnard.dev/docs/getting-started) for connection guides.

## Ecosystem

- **[@bonnard/cli](https://www.npmjs.com/package/@bonnard/cli)** — scaffold projects, deploy models, connect agents
- **[@bonnard/sdk](https://www.npmjs.com/package/@bonnard/sdk)** — query the semantic layer from JavaScript/TypeScript
- **[@bonnard/react](https://www.npmjs.com/package/@bonnard/react)** — React chart components and dashboard viewer

## Community

- [Discord](https://discord.com/invite/RQuvjGRz): ask questions, share feedback, connect with the team
- [GitHub Issues](https://github.com/bonnard-data/bonnard/issues): bug reports and feature requests
- [LinkedIn](https://www.linkedin.com/company/bonnarddev/): follow for updates
- [Website](https://www.bonnard.dev): learn more about Bonnard

## License

[Apache 2.0](./LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bonnard-data](https://github.com/bonnard-data)
- **Source:** [bonnard-data/bonnard](https://github.com/bonnard-data/bonnard)
- **License:** Apache-2.0
- **Homepage:** https://bonnard.dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-bonnard-data-bonnard
- Seller: https://agentstack.voostack.com/s/bonnard-data
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.