@@ -60,6 +62,53 @@ Milvaion solves these problems by **completely separating scheduling from execut
---
+## Already Running Hangfire or Quartz.NET?
+
+**You don't have to migrate to adopt Milvaion.**
+
+Milvaion plugs into the scheduler you already run. Your scheduler keeps owning triggers, storage and cron expressions. Your job code doesn't change. Milvaion adds one real-time dashboard across every service, plus persisted execution history, metrics and alerting.
+
+```csharp
+// Hangfire - your existing setup stays exactly as it is
+builder.Services.AddMilvaionHangfireIntegration(builder.Configuration);
+builder.Services.AddHangfire((sp, config) => config.UseMilvaion(sp));
+
+// Quartz.NET - your existing setup stays exactly as it is
+builder.Services.AddMilvaionQuartzIntegration(builder.Configuration);
+builder.Services.AddQuartz(q => q.UseMilvaion(builder.Services));
+```
+
+That's the whole integration.
+
+### The problem this solves
+
+A typical .NET estate ends up with background jobs scattered across a dozen services — each with its own dashboard behind its own URL and its own auth. Nobody can answer *"which jobs failed last night?"* without opening every one of them, and history vanishes when the retention window rolls over.
+
+| Before | After |
+|--------|-------|
+| One dashboard per service | One dashboard for the whole estate |
+| History limited by Hangfire/Quartz retention | Full execution history in PostgreSQL |
+| Logs only in each app's own sink | Real-time log streaming per execution |
+| Failures noticed when someone complains | Multi-channel alerts on failure and timeout |
+| No cross-service metrics | Success rate, duration and EPM per job |
+
+### The adoption path
+
+1. **Add monitoring** — two lines per application. No migration window, no change to job code.
+2. **Get visibility** — every Hangfire and Quartz.NET job appears in the dashboard, flagged as external.
+3. **Migrate selectively, or never** — when one job outgrows in-process execution, move just that job to a Milvaion worker. Everything else keeps running untouched.
+
+Plenty of teams stop at step 2. That's a perfectly good outcome.
+
+| Scheduler | Package | Status |
+|-----------|---------|--------|
+| **Hangfire** | `Milvasoft.Milvaion.Sdk.Worker.Hangfire` | ✅ Available |
+| **Quartz.NET** | `Milvasoft.Milvaion.Sdk.Worker.Quartz` | ✅ Available |
+
+📖 **[Full Integration Guide →](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/external-schedulers)**
+
+---
+
## Features
@@ -105,26 +154,28 @@ Milvaion solves these problems by **completely separating scheduling from execut
- **Maintenance Worker** - Milvaion self data warehouse cleanup and archival
### External Scheduler Integration
-Already using **Quartz.NET** or **Hangfire**? Keep your existing scheduler and gain Milvaion's monitoring capabilities:
-
-| Scheduler | Package | Status |
-|-----------|---------|--------|
-| **Quartz.NET** | `Milvasoft.Milvaion.Sdk.Worker.Quartz` | ✅ Available |
-| **Hangfire** | `Milvasoft.Milvaion.Sdk.Worker.Hangfire` | ✅ Available |
+Milvaion also monitors jobs running in **Quartz.NET** and **Hangfire** without replacing them — see [Already Running Hangfire or Quartz.NET?](#already-running-hangfire-or-quartznet) above.
-```csharp
-// Quartz.NET Integration
-builder.Services.AddMilvaionQuartzIntegration(builder.Configuration);
-builder.Services.AddQuartz(q => q.UseMilvaion(builder.Services));
+### MCP Server
+Point Claude Code, Cursor or GitHub Copilot at Milvaion and ask about your jobs in plain language:
-// Hangfire Integration
-builder.Services.AddMilvaionHangfireIntegration(builder.Configuration);
-builder.Services.AddHangfire((sp, config) => config.UseMilvaion(sp));
+```json
+{
+ "mcpServers": {
+ "milvaion": {
+ "type": "http",
+ "url": "https://milvaion.yourcompany.com/mcp",
+ "headers": { "X-ApiKey": "your-api-key" }
+ }
+ }
+}
```
-External jobs appear in Milvaion dashboard with full monitoring, metrics, and execution history - without changing your existing scheduler setup.
+> *"Which jobs failed last night and why?"*
+
+More than forty tools — reading, triggering, pausing, editing and deleting — each gated by the same permissions used everywhere else. A read-only api key gives an assistant full visibility and no ability to change anything. Milvaion is the data source here; it never calls a language model and stores no model provider keys.
-[For more information...](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/external-schedulers)
+📖 **[MCP Server Guide →](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/mcp-server)**
---
@@ -378,6 +429,9 @@ Each workflow can also configure **Max Step Retries** and a **Timeout** (auto-ca
| Document | Description |
|----------|-------------|
| [Introduction](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/introduction) | What is Milvaion, when to use it |
+| [Hangfire & Quartz.NET Integration](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/external-schedulers) | Keep your existing scheduler, add Milvaion monitoring |
+| [Api Keys](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/api-keys) | Credentials for CI pipelines, scripts and MCP clients |
+| [MCP Server](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/mcp-server) | Connect Claude Code, Cursor or Copilot to Milvaion |
| [Quick Start](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/quick-start) | Get running in under 10 minutes |
| [Core Concepts](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/core-concepts) | Architecture and key terms |
| [Your First Worker](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/your-first-worker) | Create a custom worker |
@@ -397,6 +451,7 @@ Each workflow can also configure **Max Step Retries** and a **Timeout** (auto-ca
| [Architecture](./docs/githubdocs/ARCHITECTURE.md) | Technical architecture deep-dive |
| [Development](./docs/githubdocs/DEVELOPMENT.md) | Development environment setup |
| [Worker SDK](./docs/githubdocs/WORKER-SDK.md) | Worker SDK reference |
+| [MCP Server](./docs/githubdocs/MCP-SERVER.md) | MCP server and api key auth internals |
| [Security](./SECURITY.md) | Security policies |
---
diff --git a/docs/githubdocs/MCP-SERVER.md b/docs/githubdocs/MCP-SERVER.md
new file mode 100644
index 0000000..fd05df4
--- /dev/null
+++ b/docs/githubdocs/MCP-SERVER.md
@@ -0,0 +1,260 @@
+# MCP Server
+
+This document covers the internals of Milvaion's Model Context Protocol server and the api key authentication it depends on. For user-facing setup instructions see the [MCP Server](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/mcp-server) and [Api Keys](https://portal.milvasoft.com/docs/1.0.1/open-source-libs/milvaion/api-keys) portal docs.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Api Key Authentication](#api-key-authentication)
+- [MCP Server Wiring](#mcp-server-wiring)
+- [Authorization Inside Tools](#authorization-inside-tools)
+- [Adding a Tool](#adding-a-tool)
+- [Design Decisions](#design-decisions)
+- [Testing](#testing)
+
+---
+
+## Overview
+
+Milvaion is an MCP **server**: it exposes its own data as tools that an MCP client (Claude Code, Cursor, Copilot) can call. Milvaion never talks to a language model and holds no model provider credentials.
+
+```text
+MCP client Milvaion.Api
+ │
+ │ POST /mcp (JSON-RPC, X-ApiKey header)
+ ▼
+ApiKeyAuthenticationHandler ──▶ ApiKeyStore (Redis cache ─▶ Postgres)
+ │ ClaimsPrincipal with permissions as role claims
+ ▼
+MapMcp endpoint ──▶ tool method ──▶ McpPermissionGuard.Require(...)
+ │
+ ▼
+ IMediator ──▶ existing CQRS query
+```
+
+### Source Layout
+
+| Path | Contains |
+|------|----------|
+| `src/Milvaion.Api/Mcp/MilvaionJobTools.cs` | Job and occurrence tools, including CRUD |
+| `src/Milvaion.Api/Mcp/MilvaionOpsTools.cs` | Worker, workflow and dashboard tools |
+| `src/Milvaion.Api/Mcp/MilvaionDiagnosticsTools.cs` | Dead letter failures and the activity log |
+| `src/Milvaion.Api/Mcp/MilvaionInsightTools.cs` | Metric reports, infrastructure health, configuration |
+| `src/Milvaion.Api/Mcp/MilvaionPrompts.cs` | Prompt templates for diagnosis workflows |
+| `src/Milvaion.Api/Mcp/McpPermissionGuard.cs` | Per-tool permission enforcement |
+| `src/Milvaion.Api/AppStartup/McpExtensions.cs` | Registration and endpoint mapping |
+| `src/Milvaion.Api/Utils/ApiKeyAuthenticationHandler.cs` | Authentication scheme |
+| `src/Milvaion.Api/Utils/KeyHelper.cs` | Key generation and signature validation |
+| `src/Milvaion.Api/Services/ApiKeyStore.cs` | Cached key lookup and cache invalidation |
+| `src/Milvaion.Api/Services/ApiKeyGenerator.cs` | `IApiKeyGenerator` implementation |
+| `src/Milvaion.Application/Features/ApiKeys/` | Api key CQRS features |
+
+Dependency: `ModelContextProtocol.AspNetCore`.
+
+---
+
+## Api Key Authentication
+
+### Key Format
+
+A key is a JWT signed with `MilvaionConfig.ApiKey.Secret` (HMAC-SHA256), carrying:
+
+| Claim | Meaning |
+|-------|---------|
+| `jti` | Id of the `MilvaionApiKey` record |
+| `kv` | Version of the signing secret |
+| `exp` | Expiry, omitted for keys that never expire |
+
+The key itself is **never persisted**. Only `MaskedKey` — the trailing characters — is stored, purely so a user can match a listed key against the one in their configuration.
+
+### Why a Record Lookup
+
+Signature validation alone would be enough to prove a key is authentic, but a self-contained token cannot be revoked. Authentication therefore always resolves `jti` to a `MilvaionApiKey` row and checks `RevokedAt`, `ExpiresAt` and `KeyVersion` before accepting the request.
+
+That lookup is cached in **Redis**, not in process memory. With several API replicas an in-process cache would leave a revoked key working on every replica that did not happen to handle the revoke request. `RevokeApiKeyCommandHandler` and `DeleteApiKeyCommandHandler` call `IApiKeyCacheInvalidator.InvalidateAsync` so revocation takes effect immediately across the cluster.
+
+If Redis is unavailable, `ApiKeyStore` falls back to the database rather than failing authentication — a cache outage should not lock every integration out.
+
+### Permissions as Role Claims
+
+`AuthAttribute` derives from `AuthorizeAttribute` and matches on `Roles`. `ApiKeyAuthenticationHandler` therefore emits each granted permission as a `ClaimTypes.Role` claim, exactly as the login token does:
+
+```csharp
+claims.AddRange(apiKey.Permissions.Select(p => new Claim(ClaimTypes.Role, p)));
+claims.Add(new Claim(GlobalConstant.UserTypeClaimName, nameof(UserType.Manager)));
+```
+
+The consequence is that **every existing `[Auth(PermissionCatalog...)]` attribute already works for api key callers** with no change. Had this been implemented as an action filter instead of an authentication scheme, authorization would have had to be reimplemented separately for machine callers.
+
+The default authorization policy names both schemes:
+
+```csharp
+options.DefaultPolicy = new AuthorizationPolicyBuilder(
+ JwtBearerDefaults.AuthenticationScheme,
+ ApiKeyAuthenticationDefaults.AuthenticationScheme)
+ .RequireAuthenticatedUser()
+ .Build();
+```
+
+### LastUsedAt Throttling
+
+`LastUsedAt` would otherwise mean a database write on every request. `ApiKeyStore.ShouldWriteLastUsedAsync` uses a Redis `SET ... NX EX` as both throttle and lock: whoever sets the key owns that interval. Default interval is five minutes, configurable through `ApiKeyAuthenticationOptions.LastUsedWriteInterval`.
+
+Failures here are swallowed and logged. Bookkeeping must never fail an otherwise valid request.
+
+### `ApiAuthAttribute`
+
+`[ApiAuth]` restricts an endpoint to api key callers only, for endpoints that should not be reachable from a browser session. `[Auth]` accepts both. All parsing and validation lives in the authentication handler; the attribute only selects the scheme and applies the permission requirement.
+
+---
+
+## MCP Server Wiring
+
+Registration is in `McpExtensions.AddMilvaionMcp`:
+
+```csharp
+services.AddMcpServer(options => { /* ServerInfo, ServerInstructions */ })
+ .WithHttpTransport(options => options.Stateless = true)
+ .WithToolsFromAssembly();
+```
+
+`WithToolsFromAssembly` discovers every `[McpServerToolType]` class and registers each `[McpServerTool]` method. Tool classes are resolved from DI per request, so constructor injection of scoped services works.
+
+Mapping is in `McpExtensions.MapMilvaionMcp`:
+
+```csharp
+app.MapMcp("/mcp").RequireAuthorization();
+```
+
+> **Ordering matters.** `MapMilvaionMcp()` must be called before `MapFallbackToFile("index.html")` in `Program.cs`, or the SPA fallback swallows `/mcp`.
+
+### ServerInstructions
+
+`ServerInstructions` is sent to the client at initialize and shapes how the model uses the server. Milvaion's explains the job/occurrence distinction, steers diagnosis towards `list_failures` rather than `list_occurrences`, and tells the model to confirm before triggering anything. In practice this affects tool selection accuracy more than any individual tool description.
+
+---
+
+## Authorization Inside Tools
+
+MCP tools are not MVC actions, so `[Auth]` never runs for them. Authentication is still enforced at the endpoint, but the per-permission check has to happen in the tool body:
+
+```csharp
+_guard.Require(PermissionCatalog.ScheduledJobManagement.List);
+```
+
+`McpPermissionGuard` reads `HttpContext.User`, honours `App.SuperAdmin`, and throws `McpException` otherwise. The message names the missing permission on purpose — an agent told exactly what it lacks stops retrying and can report something actionable.
+
+`Has(permission)` is available for trimming optional detail out of a response instead of failing the whole call.
+
+---
+
+## Adding a Tool
+
+1. Add a method to an existing `[McpServerToolType]` class, or create a new one — `WithToolsFromAssembly` finds it either way.
+2. Call `_guard.Require(...)` **first**, before any work.
+3. Delegate to the existing MediatR query or command. Do not reimplement data access; a change to filtering or projection should show up identically in the dashboard, the REST API and MCP.
+4. Write a `[Description]` aimed at a model, not a developer: say when to reach for this tool rather than another one.
+5. Add XML docs to match the rest of the codebase.
+
+```csharp
+///
+/// Gets scheduled jobs.
+///
+/// Free text search over job names and types.
+///
+/// Paged job list with the total count.
+[McpServerTool(Name = "list_jobs")]
+[Description("Lists scheduled jobs in Milvaion. Use this to find a job's id before calling other tools.")]
+public async Task