@sendinel/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,113 @@
+# @sendinel/mcp-server
+
+Sendinel's published MCP server package for local stdio clients such as Claude Desktop, Claude Code, Cursor, and Codex CLI.
+
+AI-controlled email operations control plane for campaigns, contacts, segments, templates, analytics, deliverability, and multi-provider sending across the Sendinel portfolio.
+
+- Categories: `email`, `marketing`, `crm`, `automation`, `analytics`
+- Official registry name: `io.github.kmdesle/sendinel`
+- Hosted remote endpoint: `https://sendinel.ai/mcp`
+- npm package: `@sendinel/mcp-server`
+- Source: `https://github.com/kmdesle/sendinel-ai/tree/main/packages/mcp-server`
+
+## Tool groups
+
+Sendinel currently exposes 21 tool groups and about 155 tools. The full reference lives in [`docs/mcp-tools.md`](../../docs/mcp-tools.md).
+
+| Group | Count | Purpose |
+|-------|-------|---------|
+| `campaigns` | 26 | Full campaign lifecycle |
+| `contacts` | 22 | Subscriber CRUD, tags, suppression, merges, timelines |
+| `analytics` | 9 | Stats, engagement, deliverability, portfolio reporting |
+| `data` | 15 | Export, scoring, hygiene, migrations, import history |
+| `org` | 15 | Team members, API keys, platform connections, plan, onboarding |
+| `templates` | 7 | Template CRUD, AI brief generation, translation |
+| `sms` | 7 | SMS send, consent, inbound, logs |
+| `segments` | 6 | Audience builder and preview |
+| `content` | 5 | Content blocks, sources, send-time optimization |
+| `ab_testing` | 5 | A/B setup and significance checks |
+| `drafts` | 4 | Draft create and approval flow |
+| `delivery` | 9 | Domain and deliverability operations |
+| `warmup` | 4 | Warmup schedule controls |
+| `social` | 4 | Social campaigns and scheduling |
+| `forms` | 3 | Forms and stats |
+| `webhooks` | 4 | Webhook subscription management |
+| `approvals` | 3 | Approval workflow and advisor hooks |
+| `automations` | 4 | Automation triggers and previews |
+| `sites` | 3 | Site and sender management |
+| `gdpr` | 2 | Contact deletion and log |
+| `history` | 3 | Chat thread history and search |
+
+## Install / run
+
+```bash
+npx -y @sendinel/mcp-server@latest
+```
+
+The package also exposes the legacy bin alias:
+
+```bash
+npx -y sendinel-mcp
+```
+
+## Required environment
+
+- `SENDINEL_API_KEY`
+
+Optional server-side env when you run the package outside the main Sendinel app environment:
+
+- `SUPABASE_URL` or `NEXT_PUBLIC_SUPABASE_URL`
+- `SUPABASE_SERVICE_ROLE_KEY`
+- `MCP_TRANSPORT` (`stdio` by default, `http` for HTTP/SSE mode)
+- `MCP_SERVER_PORT` (HTTP mode only)
+
+Stdio mode fails closed if `SENDINEL_API_KEY` is missing or invalid.
+
+## MCP client examples
+
+### Claude Desktop / Cursor
+
+```json
+{
+  "mcpServers": {
+    "sendinel": {
+      "command": "npx",
+      "args": ["-y", "@sendinel/mcp-server@latest"],
+      "env": {
+        "SENDINEL_API_KEY": "snk_your_api_key"
+      }
+    }
+  }
+}
+```
+
+### Codex CLI
+
+```toml
+[mcp_servers.sendinel]
+command = "npx"
+args = ["-y", "@sendinel/mcp-server@latest"]
+
+[mcp_servers.sendinel.env]
+SENDINEL_API_KEY = "snk_your_api_key"
+```
+
+Or add it automatically:
+
+```bash
+codex mcp add sendinel --env SENDINEL_API_KEY=snk_your_api_key -- npx "-y" "@sendinel/mcp-server@latest"
+```
+
+## Transport
+
+- `stdio` by default
+- `http` when `MCP_TRANSPORT=http`
+
+## Publishing
+
+This package is intended to be published publicly to npm and listed in MCP directories:
+
+- package name: `@sendinel/mcp-server`
+- default launcher: `npx -y @sendinel/mcp-server@latest`
+- official registry manifest: [`server.json`](./server.json)
+- Smithery config: [`../../smithery.yaml`](../../smithery.yaml)

package/build/anthropic-model.d.ts

@@ -0,0 +1,5 @@
+export { FALLBACK_MODEL_IDS, MODEL_REGISTRY, ROLE, getAnthropicFastModelId, getAnthropicFrontierModelId, getAnthropicModelId, getAnthropicReasoningModelId, getModelIdForRole, resolveModel, type ModelMetadata, type ModelRole, type ResolvedModel, } from '@desler/models';
+export declare const DEFAULT_ANTHROPIC_MODEL_ID: string;
+export declare const DEFAULT_ANTHROPIC_FAST_MODEL_ID: string;
+export declare const DEFAULT_ANTHROPIC_OPUS_MODEL_ID: string;
+export { getAnthropicReasoningModelId as getAnthropicOpusModelId } from '@desler/models';

package/build/anthropic-model.js

@@ -0,0 +1,6 @@
+export { FALLBACK_MODEL_IDS, MODEL_REGISTRY, ROLE, getAnthropicFastModelId, getAnthropicFrontierModelId, getAnthropicModelId, getAnthropicReasoningModelId, getModelIdForRole, resolveModel, } from '@desler/models';
+import { MODEL_REGISTRY } from '@desler/models';
+export const DEFAULT_ANTHROPIC_MODEL_ID = MODEL_REGISTRY.default.id;
+export const DEFAULT_ANTHROPIC_FAST_MODEL_ID = MODEL_REGISTRY.fast.id;
+export const DEFAULT_ANTHROPIC_OPUS_MODEL_ID = MODEL_REGISTRY.reasoning.id;
+export { getAnthropicReasoningModelId as getAnthropicOpusModelId } from '@desler/models';

package/build/audit.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Log a consent record for GDPR compliance.
+ * Used by MCP tools that modify contact subscription state.
+ */
+export declare function logConsent(opts: {
+    contactId: string;
+    siteId?: string;
+    action: 'grant' | 'revoke';
+    consentType: string;
+    source: string;
+}): Promise<void>;
+/**
+ * Log an audit trail entry.
+ * Used by MCP tools for mutation tracking.
+ */
+export declare function logAudit(opts: {
+    action: string;
+    resourceType: string;
+    resourceId?: string;
+    details?: Record<string, unknown>;
+}): Promise<void>;

package/build/audit.js

@@ -0,0 +1,38 @@
+import { db } from './db.js';
+import { getProjectId } from './project.js';
+/**
+ * Log a consent record for GDPR compliance.
+ * Used by MCP tools that modify contact subscription state.
+ */
+export async function logConsent(opts) {
+    const projectId = getProjectId();
+    await db()
+        .from('consent_records')
+        .insert({
+        project_id: projectId,
+        contact_id: opts.contactId,
+        site_id: opts.siteId ?? null,
+        action: opts.action,
+        consent_type: opts.consentType,
+        source: opts.source,
+    })
+        .then(() => { }, () => { }); // fire-and-forget
+}
+/**
+ * Log an audit trail entry.
+ * Used by MCP tools for mutation tracking.
+ */
+export async function logAudit(opts) {
+    const projectId = getProjectId();
+    await db()
+        .from('audit_log')
+        .insert({
+        project_id: projectId,
+        actor_type: 'mcp',
+        action: opts.action,
+        resource_type: opts.resourceType,
+        resource_id: opts.resourceId ?? null,
+        details: opts.details ?? {},
+    })
+        .then(() => { }, () => { }); // fire-and-forget
+}

package/build/auth.d.ts

@@ -0,0 +1,10 @@
+export type ProjectPlan = 'free' | 'byod' | 'managed' | 'agency-plus' | 'enterprise';
+export interface ApiKeyInfo {
+    projectId: string;
+    scopes: string[];
+    toolGroups: string[];
+    approvalMode: string;
+}
+export declare function resolveToolGroupsForPlan(plan: string | null | undefined, requested: string[] | null | undefined): string[];
+export declare function serviceKeyInfo(projectId: string): Promise<ApiKeyInfo>;
+export declare function validateKey(key: string): Promise<ApiKeyInfo | null>;

package/build/auth.js

@@ -0,0 +1,57 @@
+import { adminDb } from './db.js';
+import { ALL_TOOL_GROUPS } from './server.js';
+const BYOD_DEFAULT_TOOL_GROUPS = ['contacts', 'templates', 'analytics'];
+export function resolveToolGroupsForPlan(plan, requested) {
+    if (requested && requested.length > 0) {
+        return requested.filter((group) => ALL_TOOL_GROUPS.includes(group));
+    }
+    switch (plan) {
+        case 'byod':
+            return BYOD_DEFAULT_TOOL_GROUPS.slice();
+        case 'managed':
+        case 'agency-plus':
+        case 'enterprise':
+            return ALL_TOOL_GROUPS.slice();
+        case 'free':
+        default:
+            return [];
+    }
+}
+async function getProjectPlan(projectId) {
+    const { data } = await adminDb()
+        .schema('email')
+        .from('projects')
+        .select('plan')
+        .eq('id', projectId)
+        .maybeSingle();
+    return data?.plan ?? 'free';
+}
+// First-party service auth for the MCP lane: the shared SYNCHRONEX_SERVICE_TOKEN
+// acts on an explicitly-named project (no per-project key lookup). Tool access is
+// resolved from the project's own plan, so the service caller gets exactly what
+// the project is entitled to — never more. Mirrors authenticateV1's service path
+// on the dashboard side.
+export async function serviceKeyInfo(projectId) {
+    const plan = await getProjectPlan(projectId);
+    return {
+        projectId,
+        scopes: ['admin'],
+        toolGroups: resolveToolGroupsForPlan(plan, null),
+        approvalMode: 'standard',
+    };
+}
+export async function validateKey(key) {
+    const { createHash } = await import('crypto');
+    const hash = createHash('sha256').update(key).digest('hex');
+    const { data, error } = await adminDb().rpc('validate_api_key', { p_key_hash: hash });
+    if (error || !data?.length)
+        return null;
+    const row = data[0];
+    const plan = await getProjectPlan(row.project_id);
+    return {
+        projectId: row.project_id,
+        scopes: row.scopes,
+        toolGroups: resolveToolGroupsForPlan(plan, row.tool_groups),
+        approvalMode: row.approval_mode ?? 'standard',
+    };
+}

package/build/byod-client.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Thrown when a project cannot be resolved to a definite client. Callers that
+ * must fail closed (the multi-tenant HTTP gateway) surface this instead of
+ * silently falling back to Sendinel's admin DB.
+ */
+export declare class TenantResolutionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve the per-project Supabase client for a given project ID (lenient).
+ *
+ * - 'sendinel' projects: returns null (tools use adminDb() / Sendinel's DB).
+ * - 'byod' projects: creates and returns a client pointed at the customer's Supabase.
+ * - any resolution failure: returns null (legacy stdio fallback to Sendinel's DB).
+ *
+ * The returned client should be passed to runWithClient() (HTTP) or setProjectClient() (stdio).
+ */
+export declare function resolveProjectClient(projectId: string): Promise<any>;
+/**
+ * Fail-closed variant for the multi-tenant HTTP gateway. Returns the BYOD client,
+ * or null ONLY for genuine 'sendinel'-type projects. Throws TenantResolutionError
+ * for any BYOD project that cannot be routed (missing/undecryptable credentials)
+ * so a misconfigured tenant never silently reads/writes Sendinel's admin DB.
+ */
+export declare function resolveProjectClientStrict(projectId: string): Promise<any>;
+/**
+ * Convenience wrapper for the stdio transport: resolves and installs the project
+ * client as the per-process fallback (called once at startup).
+ */
+export declare function initProjectClient(projectId: string): Promise<void>;

package/build/byod-client.js

@@ -0,0 +1,95 @@
+import { createClient } from '@supabase/supabase-js';
+import { adminDb, setProjectClient } from './db.js';
+import { decrypt } from './crypto.js';
+/**
+ * Thrown when a project cannot be resolved to a definite client. Callers that
+ * must fail closed (the multi-tenant HTTP gateway) surface this instead of
+ * silently falling back to Sendinel's admin DB.
+ */
+export class TenantResolutionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TenantResolutionError';
+    }
+}
+/**
+ * Core resolver. Returns:
+ *   - { type: 'sendinel' }            — project stores data in Sendinel's own DB (adminDb()).
+ *   - { type: 'byod', client }        — project routes to the customer's Supabase.
+ *
+ * Throws TenantResolutionError for projects that exist but cannot be routed
+ * definitively (not found, BYOD missing credentials, undecryptable key). Never
+ * queries the customer's DB to bootstrap itself — always uses adminDb().
+ */
+async function resolveConnector(projectId) {
+    const { data, error } = await adminDb()
+        .from('projects')
+        .select('connector_type, connector_supabase_url, connector_supabase_key_enc')
+        .eq('id', projectId)
+        .maybeSingle();
+    if (error)
+        throw new TenantResolutionError(`project lookup failed for ${projectId}: ${error.message}`);
+    if (!data)
+        throw new TenantResolutionError(`project ${projectId} not found`);
+    const row = data;
+    // Anything that is not an explicitly-configured BYOD connector resolves to the
+    // Sendinel admin DB — that is the intended store for 'sendinel'-type projects.
+    if (row.connector_type !== 'byod')
+        return { type: 'sendinel' };
+    if (!row.connector_supabase_url || !row.connector_supabase_key_enc) {
+        throw new TenantResolutionError(`BYOD project ${projectId} is missing connector credentials`);
+    }
+    let serviceKey;
+    try {
+        serviceKey = decrypt(row.connector_supabase_key_enc);
+    }
+    catch {
+        throw new TenantResolutionError(`failed to decrypt connector key for BYOD project ${projectId}`);
+    }
+    const client = createClient(row.connector_supabase_url, serviceKey, {
+        auth: { autoRefreshToken: false, persistSession: false },
+        db: { schema: 'email' },
+    });
+    // Zero key material from memory
+    serviceKey = '';
+    return { type: 'byod', client };
+}
+/**
+ * Resolve the per-project Supabase client for a given project ID (lenient).
+ *
+ * - 'sendinel' projects: returns null (tools use adminDb() / Sendinel's DB).
+ * - 'byod' projects: creates and returns a client pointed at the customer's Supabase.
+ * - any resolution failure: returns null (legacy stdio fallback to Sendinel's DB).
+ *
+ * The returned client should be passed to runWithClient() (HTTP) or setProjectClient() (stdio).
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function resolveProjectClient(projectId) {
+    try {
+        const resolved = await resolveConnector(projectId);
+        return resolved.type === 'byod' ? resolved.client : null;
+    }
+    catch (err) {
+        process.stderr.write(`[byod-client] ${err.message} — falling back to Sendinel DB\n`);
+        return null;
+    }
+}
+/**
+ * Fail-closed variant for the multi-tenant HTTP gateway. Returns the BYOD client,
+ * or null ONLY for genuine 'sendinel'-type projects. Throws TenantResolutionError
+ * for any BYOD project that cannot be routed (missing/undecryptable credentials)
+ * so a misconfigured tenant never silently reads/writes Sendinel's admin DB.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function resolveProjectClientStrict(projectId) {
+    const resolved = await resolveConnector(projectId);
+    return resolved.type === 'byod' ? resolved.client : null;
+}
+/**
+ * Convenience wrapper for the stdio transport: resolves and installs the project
+ * client as the per-process fallback (called once at startup).
+ */
+export async function initProjectClient(projectId) {
+    const client = await resolveProjectClient(projectId);
+    setProjectClient(client);
+}

package/build/crypto.d.ts

@@ -0,0 +1,2 @@
+export declare function decrypt(encrypted: string): string;
+export declare function encrypt(plaintext: string): string;

package/build/crypto.js

@@ -0,0 +1,27 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'crypto';
+function getKey() {
+    const hex = process.env.SENDINEL_ENCRYPTION_KEY;
+    if (!hex)
+        throw new Error('SENDINEL_ENCRYPTION_KEY env var is required');
+    const buf = Buffer.from(hex, 'hex');
+    if (buf.length !== 32)
+        throw new Error('SENDINEL_ENCRYPTION_KEY must be 32 bytes (64 hex chars)');
+    return buf;
+}
+export function decrypt(encrypted) {
+    const key = getKey();
+    const [ivHex, ciphertextHex, tagHex] = encrypted.split(':');
+    if (!ivHex || !ciphertextHex || !tagHex)
+        throw new Error('Invalid encrypted format');
+    const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(ivHex, 'hex'));
+    decipher.setAuthTag(Buffer.from(tagHex, 'hex'));
+    return decipher.update(ciphertextHex, 'hex', 'utf8') + decipher.final('utf8');
+}
+export function encrypt(plaintext) {
+    const key = getKey();
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return `${iv.toString('hex')}:${ciphertext.toString('hex')}:${tag.toString('hex')}`;
+}

package/build/db.d.ts

@@ -0,0 +1,38 @@
+import 'dotenv/config';
+/** Returns Sendinel's admin client. Always points to Sendinel's Supabase — never overridden. */
+export declare function adminDb(): any;
+/**
+ * Set the per-process project client (stdio only).
+ * Called once at startup after resolving the project's connector config.
+ * Has no effect inside runWithClient() — the per-request store takes precedence.
+ */
+export declare function setProjectClient(client: any): void;
+/**
+ * Run fn with a per-request project client bound to the current async context.
+ * Safe under concurrent HTTP requests — each request's tool handlers see only
+ * their own client, regardless of what other concurrent requests are doing.
+ *
+ * @param client - The resolved project client (BYOD customer's Supabase, or null for Sendinel's).
+ * @param fn     - Async function to run within this client's context.
+ */
+export declare function runWithClient<T>(client: any, fn: () => Promise<T>, request?: {
+    projectId?: string;
+    approvalMode?: string;
+}): Promise<T>;
+/**
+ * Request-scoped identity set via runWithClient() (HTTP transport).
+ * Undefined under stdio, where the process env is the single-project source of truth.
+ */
+export declare function requestContext(): {
+    projectId?: string;
+    approvalMode?: string;
+} | undefined;
+/**
+ * Returns the project client appropriate for the current execution context:
+ *   1. Per-request store (HTTP): set via runWithClient() — safe under concurrency.
+ *   2. Per-process fallback (stdio): set via setProjectClient() at startup.
+ *   3. Sendinel admin DB: if no override is set (sendinel-type project).
+ *
+ * Use this in all tool handlers for customer data reads/writes.
+ */
+export declare function db(): any;

package/build/db.js

@@ -0,0 +1,70 @@
+import 'dotenv/config';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createClient } from '@supabase/supabase-js';
+// Sendinel's own Supabase (always used for infrastructure: API key validation, plan limits)
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _adminClient = null;
+const _requestStore = new AsyncLocalStorage();
+// Per-process fallback (stdio transport — single-project, set once at startup)
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _processClient = null;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function buildAdminClient() {
+    const url = process.env.SUPABASE_URL;
+    const key = process.env.SUPABASE_SERVICE_ROLE_KEY;
+    if (!url || !key)
+        throw new Error('SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY must be set');
+    return createClient(url, key, {
+        auth: { autoRefreshToken: false, persistSession: false },
+        db: { schema: 'email' },
+    });
+}
+/** Returns Sendinel's admin client. Always points to Sendinel's Supabase — never overridden. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function adminDb() {
+    if (!_adminClient)
+        _adminClient = buildAdminClient();
+    return _adminClient;
+}
+/**
+ * Set the per-process project client (stdio only).
+ * Called once at startup after resolving the project's connector config.
+ * Has no effect inside runWithClient() — the per-request store takes precedence.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function setProjectClient(client) {
+    _processClient = client;
+}
+/**
+ * Run fn with a per-request project client bound to the current async context.
+ * Safe under concurrent HTTP requests — each request's tool handlers see only
+ * their own client, regardless of what other concurrent requests are doing.
+ *
+ * @param client - The resolved project client (BYOD customer's Supabase, or null for Sendinel's).
+ * @param fn     - Async function to run within this client's context.
+ */
+export async function runWithClient(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+client, fn, request) {
+    return _requestStore.run({ client, ...request }, fn);
+}
+/**
+ * Request-scoped identity set via runWithClient() (HTTP transport).
+ * Undefined under stdio, where the process env is the single-project source of truth.
+ */
+export function requestContext() {
+    const ctx = _requestStore.getStore();
+    return ctx ? { projectId: ctx.projectId, approvalMode: ctx.approvalMode } : undefined;
+}
+/**
+ * Returns the project client appropriate for the current execution context:
+ *   1. Per-request store (HTTP): set via runWithClient() — safe under concurrency.
+ *   2. Per-process fallback (stdio): set via setProjectClient() at startup.
+ *   3. Sendinel admin DB: if no override is set (sendinel-type project).
+ *
+ * Use this in all tool handlers for customer data reads/writes.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function db() {
+    return _requestStore.getStore()?.client ?? _processClient ?? adminDb();
+}

package/build/index.d.ts

@@ -0,0 +1 @@
+export {};

package/build/index.js

@@ -0,0 +1,97 @@
+import { config } from 'dotenv';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+config({ path: resolve(__dirname, '../.env') });
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import express from 'express';
+import { registerAllTools } from './server.js';
+import { runWithClient } from './db.js';
+import { initProjectClient, resolveProjectClient } from './byod-client.js';
+import { serviceKeyInfo, validateKey } from './auth.js';
+const transport = process.env.MCP_TRANSPORT ?? 'stdio';
+async function runStdio() {
+    const server = new McpServer({ name: 'sendinel', version: '0.1.0' });
+    // For stdio, validate SENDINEL_API_KEY and fail closed if it is absent.
+    const apiKey = process.env.SENDINEL_API_KEY;
+    let toolGroups;
+    let scopes;
+    if (!apiKey) {
+        process.stderr.write('SENDINEL_API_KEY is required for stdio transport\n');
+        process.exit(1);
+    }
+    const info = await validateKey(apiKey);
+    if (!info) {
+        process.stderr.write('Invalid SENDINEL_API_KEY\n');
+        process.exit(1);
+    }
+    toolGroups = info.toolGroups;
+    scopes = info.scopes?.length ? info.scopes : undefined;
+    process.env.SENDINEL_PROJECT_ID = info.projectId;
+    // Initialize per-project client (BYOD: routes db() to customer's Supabase)
+    const projectId = process.env.SENDINEL_PROJECT_ID;
+    if (projectId) {
+        await initProjectClient(projectId);
+    }
+    registerAllTools(server, { toolGroups, scopes });
+    const t = new StdioServerTransport();
+    await server.connect(t);
+    process.stderr.write('Sendinel MCP server running (stdio)\n');
+}
+async function runHttp() {
+    const port = parseInt(process.env.MCP_SERVER_PORT ?? '3001', 10);
+    const app = express();
+    app.use(express.json());
+    app.use('/mcp', async (req, res, next) => {
+        const authHeader = req.headers.authorization;
+        if (!authHeader?.startsWith('Bearer ')) {
+            res.status(401).json({ error: 'Missing API key. Use Authorization: Bearer snk_...' });
+            return;
+        }
+        const key = authHeader.slice(7);
+        let info = await validateKey(key);
+        if (!info) {
+            res.status(401).json({ error: 'Invalid or revoked API key' });
+            return;
+        }
+        // First-party service key (service:provision scope) may target any project
+        // via X-Sendinel-Project-Id, so Synchronex drives the bundled MCP lane
+        // without storing a per-project key. Other keys ignore the header.
+        const overrideProjectId = req.headers['x-sendinel-project-id']?.trim();
+        if (overrideProjectId && info.scopes?.includes('service:provision')) {
+            info = await serviceKeyInfo(overrideProjectId);
+        }
+        req._apiKeyInfo = info;
+        next();
+    });
+    app.post('/mcp', async (req, res) => {
+        const info = req._apiKeyInfo;
+        // Resolve the per-project client (null for sendinel-type projects).
+        // runWithClient() binds it — plus projectId/approvalMode — to this request's
+        // AsyncLocalStorage context. Nothing request-scoped may be written to
+        // process.env here: it is process-global and leaks across concurrent tenants.
+        const projectClient = await resolveProjectClient(info.projectId);
+        await runWithClient(projectClient, async () => {
+            const server = new McpServer({ name: 'sendinel', version: '0.1.0' });
+            registerAllTools(server, {
+                scopes: info.scopes,
+                toolGroups: info.toolGroups,
+            });
+            const t = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+            await server.connect(t);
+            await t.handleRequest(req, res, req.body);
+        }, { projectId: info.projectId, approvalMode: info.approvalMode });
+    });
+    app.get('/health', (_req, res) => res.json({ ok: true }));
+    app.listen(port, () => {
+        console.log(`Sendinel MCP server running on http://localhost:${port}/mcp`);
+    });
+}
+if (transport === 'http') {
+    runHttp().catch((err) => { console.error(err); process.exit(1); });
+}
+else {
+    runStdio().catch((err) => { console.error(err); process.exit(1); });
+}

package/build/lib/action-approvals.d.ts

@@ -0,0 +1,30 @@
+export type ApprovalTier = 'autonomous' | 'gated' | 'protected';
+export declare function getApprovalTier(action: string, params?: Record<string, unknown>): ApprovalTier;
+/** Build a human-readable summary of the action for the approval screen */
+export declare function buildApprovalSummary(action: string, params: Record<string, unknown>): string;
+export interface ApprovalResult {
+    requires_approval: true;
+    approval_id: string;
+    tier: ApprovalTier;
+    action: string;
+    summary: string;
+    expires_at: string;
+    approve_via: string;
+    message: string;
+}
+/**
+ * Request human approval for an action. Creates a pending approval token
+ * and returns instructions for the agent to wait.
+ */
+export declare function requestApproval(action: string, params: Record<string, unknown>, apiKeyId?: string): Promise<ApprovalResult>;
+/**
+ * Check if an approval token has been approved.
+ * Returns the approval if approved, null if still pending, throws if rejected/expired.
+ */
+export declare function checkApproval(approvalId: string, options?: {
+    consume?: boolean;
+}): Promise<{
+    approved: boolean;
+    status: string;
+    decided_by?: string;
+}>;