# Beacon

> Beacon is a .NET 10 platform for database monitoring, alerting and data movement, with a governed Model Context Protocol (MCP) server that gives AI assistants read-only, project-scoped, masked and audited access to your databases. It runs standalone or is embedded in an ASP.NET Core application through the Moberg.Beacon.* NuGet packages.

To integrate Beacon into an application, read the integration bundle first:

- [Integration guide (all integration pages, one file)](https://moberghr.github.io/beacon/llms-integrate.txt): everything needed to embed Beacon in an ASP.NET Core host
- [Full documentation (one file)](https://moberghr.github.io/beacon/llms-full.txt): every page of these docs

## Start here

What Beacon is, its core concepts, and running it locally in minutes.

- [Overview](https://moberghr.github.io/beacon/getting-started.md): What Beacon is, who it is for, the two ways to run it, and what you need before you start.
- [Core concepts](https://moberghr.github.io/beacon/getting-started/concepts.md): The mental model behind Beacon: data sources, projects, queries, subscriptions, recipients, tasks, data contracts, approvals, the SQL execution gate, the MCP server, roles and audit.
- [Quick start](https://moberghr.github.io/beacon/getting-started/quick-start.md): Run the Beacon sample host from a clone and send your first alert end to end: data source, project, query, recipient and subscription.
- [Run the sample host](https://moberghr.github.io/beacon/getting-started/installation.md): Reference for Beacon.SampleProject, the sample host in the repository: what it wires, the configuration it reads, ports, Warp jobs, the UI build, running outside Development and publishing a release.

## Integrate Beacon

Embed Beacon in your own ASP.NET Core application: packages, host wiring, database, sign-in, access control, jobs, connectors, AI, MCP and production.

- [Integrate Beacon into your application](https://moberghr.github.io/beacon/integrate.md): The step-by-step checklist for embedding Beacon in an ASP.NET Core host: packages, Program.cs, database, sign-in, jobs, connectors, AI, MCP and production, written for people and for coding agents.
- [Packages](https://moberghr.github.io/beacon/integrate/packages.md): Every Moberg.Beacon NuGet package, what it contains, which ones you need, and how versions are published.
- [Host wiring](https://moberghr.github.io/beacon/integrate/host-setup.md): A complete, annotated Program.cs for embedding Beacon: service registration, the load-bearing middleware order, endpoint mapping, startup migration, and every option of AddBeaconServices.
- [Metadata database](https://moberghr.github.io/beacon/integrate/database.md): Where Beacon keeps its own data: PostgreSQL with pgvector or SQL Server, the fixed beacon schema, how to create and migrate it, and how to hand Beacon your own NpgsqlDataSource.
- [Sign-in & identity](https://moberghr.github.io/beacon/integrate/authentication.md): Every way a person or program proves who it is to Beacon: first-run setup, local passwords and break-glass accounts, OIDC/Entra SSO with MFA, bearer JWTs, API keys, sessions and your own sign-in.
- [Access control](https://moberghr.github.io/beacon/integrate/access-control.md): Decide who sees what before go-live: global roles, projects as the access boundary, functional permissions, separation of duties, IdP role mapping, change approvals and deployment locks.
- [Background jobs](https://moberghr.github.io/beacon/integrate/background-jobs.md): Beacon runs no background work of its own; your job runner does. The IBeaconScheduler contract, the jobs Beacon expects, the system-work rule, a complete Warp implementation, and a Hangfire sketch.
- [Data-source connectors](https://moberghr.github.io/beacon/integrate/connectors.md): Register the connectors for the engines Beacon monitors, what each one supports, how read-only is enforced per engine, and how to create the read-only logins Beacon should use.
- [AI providers](https://moberghr.github.io/beacon/integrate/ai.md): Turn on Beacon's AI layer: UseAI and AddBeaconAI, the four LLM providers and their settings, the request queue, runtime switching, local embeddings for semantic retrieval, and what data reaches the provider.
- [MCP & AI clients](https://moberghr.github.io/beacon/integrate/mcp.md): Expose Beacon's MCP server from your host, decide how AI clients authenticate (API keys or Entra ID callers), publish discovery metadata, and connect Claude Code, Claude, Cursor and VS Code.
- [Extending Beacon](https://moberghr.github.io/beacon/integrate/extending.md): Make your own application part of Beacon: expose your EF Core DbContext as a read-only data source, import your Markdown docs as grounding, turn your HTTP endpoints into MCP tools, and replace Beacon's extension points.
- [Production checklist](https://moberghr.github.io/beacon/integrate/production.md): What to set before Beacon faces real users and real data: secrets, Data Protection, reverse proxy, sign-in, locks, audit, MCP, scaling, observability and upgrades.
- [Troubleshooting](https://moberghr.github.io/beacon/integrate/troubleshooting.md): Startup failures, empty pages, 401s and 404s, jobs that do nothing, MCP clients that cannot connect: symptoms, causes and fixes for an embedded Beacon.

## Monitor & move data

Data sources, multi-step queries, scheduled subscriptions, alerts, tasks, anomaly detection, data quality and data migration.

- [Features](https://moberghr.github.io/beacon/features.md): A map of every Beacon feature page: monitoring and moving data, the AI and MCP layer, and governance and security.
- [Data Sources](https://moberghr.github.io/beacon/features/data-sources.md): Connect the databases and services Beacon reads: nine connectors, credentials encrypted at rest, access through projects, and per-engine read-only guarantees.
- [Queries](https://moberghr.github.io/beacon/features/queries.md): Saved, versioned SQL: one or more steps across data sources, bound parameters, an optional in-memory final query, and an optional four-eyes review of every change.
- [Subscriptions](https://moberghr.github.io/beacon/features/subscriptions.md): Run a query on a cron schedule, decide which runs notify whom, and choose what each notification carries: runs execute as the subscription's owner.
- [Notifications](https://moberghr.github.io/beacon/features/notifications.md): Deliver subscription results through five channels (Email, Microsoft Teams, Slack, Jira and a generic webhook) to vetted, encrypted recipients, with a delivery history.
- [Control Tower](https://moberghr.github.io/beacon/features/control-tower.md): Health of every subscription you can read: health buckets, success rates, open tasks and anomaly sparklines, refreshed every 30 seconds.
- [Tasks](https://moberghr.github.io/beacon/features/tasks.md): Work items that open when a subscription's query returns rows, stay open while it keeps returning rows, and resolve themselves when it returns none.
- [Anomaly Detection](https://moberghr.github.io/beacon/features/anomaly-detection.md): Statistical detection on a subscription's row count. Beacon learns a baseline from past runs and notifies only when a run deviates from it.
- [Data Quality](https://moberghr.github.io/beacon/features/data-quality.md): Data contracts with scheduled, rule-based checks that produce a weighted quality score, track trends over time, and alert on threshold breaches.
- [Data Migration](https://moberghr.github.io/beacon/features/data-migration.md): Copy rows from a read source into a database marked as a migration write target, in Insert, Upsert or Truncate mode.

## AI & MCP

The governed MCP server, its tools and extension points, grounding, the AI layer and AI actors.

- [MCP Server](https://moberghr.github.io/beacon/features/mcp-server.md): A Model Context Protocol server that lets AI assistants query your data sources, search your catalog, and read documentation over authenticated HTTP.
- [Entra ID callers on MCP](https://moberghr.github.io/beacon/features/mcp-entra-callers.md): Let an agent platform call Beacon's MCP endpoint with Microsoft Entra ID tokens, either on behalf of a user or as a system identity, with projects and scope decided by Beacon configuration.
- [Saved Query Tools](https://moberghr.github.io/beacon/features/saved-query-tools.md): Expose approved, parameterized saved queries as named, read-only MCP tools such as q_loan_book_by_month(from, to), so agents and routines call reviewed, versioned SQL instead of carrying their own.
- [Host Endpoint Tools](https://moberghr.github.io/beacon/features/host-endpoint-tools.md): Expose selected endpoints of the host application as MCP tools (read-only by default, write tools behind an explicit opt-in) invoked in-process as the caller through the endpoint's own model binding, filters and authorization policies.
- [Host DbContext](https://moberghr.github.io/beacon/features/host-dbcontext.md): Expose the host application's own EF Core DbContext as a read-only Beacon data source: default-deny table allow-list, column exclusion and masking, no stored connection string.
- [Host Docs](https://moberghr.github.io/beacon/features/host-docs.md): Ship the host application's markdown documentation with it and import it into a Beacon project. The documents are searchable by MCP agents with or without embeddings, readable through get_documentation, and summarised in an AGENTS.md project brief.
- [Knowledge Base & SQL Grounding](https://moberghr.github.io/beacon/features/knowledge-base.md): How Beacon grounds generated SQL: M-Schema with sample values, schema relationships, a business glossary, human-verified golden examples, learned patterns, and semantic retrieval.
- [AI Integration](https://moberghr.github.io/beacon/features/ai-integration.md): How Beacon connects to an LLM provider (OpenAI, Anthropic, Azure OpenAI, AWS Bedrock), what it uses the model for, and what it sends.
- [AI Actors](https://moberghr.github.io/beacon/features/ai-actors.md): Experimental LLM-driven monitoring agents attached to a data source. They analyze it and propose queries and subscriptions; the proposals are recorded for review, not executed.
- [MCP observability and audit](https://moberghr.github.io/beacon/features/mcp-observability-and-audit.md): Every MCP tool call is auditable, correlated to a W3C trace, and optionally exported through OpenTelemetry, without Beacon choosing your telemetry backend.

## Govern & secure

The security model: projects, permissions, approvals, users, API keys, the security audit trail and admin settings.

- [Security model](https://moberghr.github.io/beacon/features/security-model.md): How Beacon protects your data end to end: identity and sessions, projects as the access boundary, functional permissions, four-eyes approvals, the single SQL execution gate, masking and LLM egress, secrets at rest, outbound notifications, the write path, deployment locks, audit and security events.
- [Authorization](https://moberghr.github.io/beacon/features/authorization.md): How Beacon decides access: projects as the boundary, global and project roles, project actions, functional permissions with a route matrix, separation of duties, identity-provider role mapping, 404 versus 403, scheduled work and shared data sources.
- [Approvals](https://moberghr.github.io/beacon/features/approvals.md): Four-eyes change approval: what it reviews (query changes, migration jobs, Custom SQL rules, notification destinations), how a decision is bound to exactly what the reviewer saw, who may approve, strict mode, and the API.
- [User Management](https://moberghr.github.io/beacon/features/user-management.md): Built-in users and roles: internal password and external identity-provider users, first-run setup, functional roles, sessions, local and single sign-on, and the sign-in routes.
- [API Keys](https://moberghr.github.io/beacon/features/api-keys.md): Scoped, SHA256-hashed API keys for programmatic access, with Read/Execute scopes, a project list, a mandatory expiry, and revocation tied to the owner's account.
- [Security audit trail](https://moberghr.github.io/beacon/features/security-audit.md): An append-only, signed record of who signed in, changed identities, keys, access, data sources, delivery, settings, saved queries, approvals, ownership, tasks, curation, data quality and migrations, for an Auditor, verified on a schedule, with a copy on the Beacon.Audit log stream for your SIEM.
- [Admin Settings](https://moberghr.github.io/beacon/features/admin-settings.md): The Admin settings page: the base URL and the LLM provider, changed at runtime and swapped without a restart, who may read or change each setting, and the settings change history.

## Reference

Configuration keys and the URLs Beacon serves.

- [Configuration](https://moberghr.github.io/beacon/getting-started/configuration.md): Every configuration key Beacon reads, grouped by area with type, default and validation; the code-only options set in AddBeaconServices; the deployment locks; and the environment-variable form.
- [Routes & endpoints](https://moberghr.github.io/beacon/reference/routes.md): Every URL Beacon serves: UI pages under /beacon, anonymous routes, REST API groups under /beacon/api, the SignalR hub, the MCP server and discovery documents, with the paging contract and error responses.

## Optional

- [Source code](https://github.com/moberghr/beacon): the reference host is src/Beacon.SampleProject/Program.cs