fodda-mcp 1.32.0 → 1.38.0

package/dist/index.js

@@ -15,6 +15,8 @@ import { cacheGet, cacheSet, getCacheStats } from './queryCache.js';
 import { MCP_SERVER_VERSION } from './tools.js';
 import { createServer } from './toolHandlers.js';
 import { registerA2ARoute } from './a2aHandler.js';
+import { registerAgentFactsRoute } from './agentFacts.js';
+import { getTelemetryStats, recordFeedbackEntry } from './telemetry.js';
 import * as dotenv from 'dotenv';
 dotenv.config();
 // ── Global crash guards ──
@@ -29,6 +31,7 @@ process.on('uncaughtException', (err) => {
     console.error('[uncaughtException] kept process alive:', err?.stack || err?.message || err);
 });
 const API_BASE_URL = process.env.FODDA_API_URL || 'https://api.fodda.ai';
+const WEBSITE_BASE_URL = process.env.WEBSITE_BASE_URL || 'https://www.fodda.ai';
 const app = express();
 app.use(express.json({ limit: '512kb' }));
 // CORS — minimal, matching test server
@@ -41,18 +44,226 @@ app.use((req, res, next) => {
         return res.status(204).end();
     next();
 });
-// OAuth discovery endpoints — return 404 to indicate no OAuth support
+// OAuth discovery endpoints — Clerk-backed OAuth for the MCP Connectors Directory.
+// The authorization server is Clerk (configured as CLERK_ISSUER_URL).
+// These endpoints follow RFC 8414 / draft-ietf-oauth-security-topics so MCP clients
+// can auto-discover the auth server and initiate PKCE flows.
+const CLERK_ISSUER = process.env.CLERK_ISSUER_URL || 'https://clerk.fodda.ai';
 app.get('/.well-known/oauth-protected-resource', (_req, res) => {
-    res.status(404).json({ error: 'OAuth not supported. Use API key auth via URL: ?api_key=YOUR_KEY' });
+    res.status(200).json({
+        resource: 'https://mcp.fodda.ai',
+        authorization_servers: [CLERK_ISSUER],
+    });
 });
-app.get('/.well-known/oauth-protected-resource/:path', (_req, res) => {
-    res.status(404).json({ error: 'OAuth not supported.' });
+app.get('/.well-known/oauth-protected-resource/mcp', (_req, res) => {
+    res.status(200).json({
+        resource: 'https://mcp.fodda.ai/mcp',
+        authorization_servers: [CLERK_ISSUER],
+    });
 });
 app.get('/.well-known/oauth-authorization-server', (_req, res) => {
-    res.status(404).json({ error: 'OAuth not supported.' });
+    res.redirect(302, `${CLERK_ISSUER}/.well-known/oauth-authorization-server`);
 });
 app.post('/register', (_req, res) => {
-    res.status(404).json({ error: 'OAuth not supported.' });
+    // DCR not handled here — managed by Clerk dashboard
+    res.status(501).json({ error: 'Dynamic client registration is managed via the Clerk dashboard.' });
+});
+// ---------------------------------------------------------------------------
+// .well-known MCP Server Discovery Card & Pricing Metadata Tier
+// ---------------------------------------------------------------------------
+export const OFFERING_SCOPED_TOOLS = {
+    'brand-intelligence': [
+        'get_capabilities',
+        'brand_tracker',
+        'search_graph',
+        'read_url',
+        'get_supplemental_context',
+        'check_supplemental_status',
+        'get_evidence',
+        'get_node',
+        'get_neighbors',
+        'get_label_values',
+        'list_graphs',
+        'get_my_account',
+        'generate_visual',
+    ],
+    'topic-research': [
+        'get_capabilities',
+        'search_graph',
+        'search_statistics',
+        'search_insights',
+        'get_validated_trends',
+        'get_evidence',
+        'get_node',
+        'get_neighbors',
+        'get_label_values',
+        'list_graphs',
+        'get_my_account',
+        'generate_visual',
+        'read_url',
+        'get_supplemental_context',
+        'check_supplemental_status',
+    ],
+    'deep-research': [
+        'get_capabilities',
+        'deep_research_topic',
+        'check_research_status',
+        'search_graph',
+        'get_evidence',
+        'get_node',
+        'get_neighbors',
+        'get_label_values',
+        'list_graphs',
+        'get_my_account',
+        'generate_visual',
+        'read_url',
+        'get_supplemental_context',
+        'check_supplemental_status',
+    ],
+    'earnings-intelligence': [
+        'get_capabilities',
+        'get_earnings_intelligence',
+        'get_earnings_divergence',
+        'get_company_earnings',
+        'get_validated_trends',
+        'search_graph',
+        'get_evidence',
+        'get_node',
+        'get_neighbors',
+        'get_label_values',
+        'list_graphs',
+        'get_my_account',
+        'generate_visual',
+    ],
+    'expert-consult': [
+        'get_capabilities',
+        'consult_analyst',
+        'list_analysts',
+        'request_deliverable',
+        'check_deliverable_status',
+        'search_graph',
+        'get_evidence',
+        'get_node',
+        'get_neighbors',
+        'get_label_values',
+        'list_graphs',
+        'get_my_account',
+        'generate_visual',
+    ],
+};
+const OFFERING_CARD_METADATA = {
+    'brand-intelligence': {
+        name: 'ai.fodda/brand-intelligence',
+        title: 'Fodda Brand Intelligence',
+        description: 'Brand health & trend footprint across PSFK expert graphs with citable sources, not web summaries.',
+    },
+    'topic-research': {
+        name: 'ai.fodda/topic-research',
+        title: 'Fodda Topic & Trend Research',
+        description: 'Trend, statistics & insight search across PSFK expert graphs with citable sources, not web summaries.',
+    },
+    'deep-research': {
+        name: 'ai.fodda/deep-research',
+        title: 'Fodda Deep Research',
+        description: 'Autonomous deep research reports merging PSFK knowledge graphs & web validation with citable sources.',
+    },
+    'earnings-intelligence': {
+        name: 'ai.fodda/earnings-intelligence',
+        title: 'Fodda Earnings Intelligence',
+        description: 'Cross-company earnings trends, executive divergence & ticker analysis with citable sources.',
+    },
+    'expert-consult': {
+        name: 'ai.fodda/expert-consult',
+        title: 'Fodda Synthetic Expert Consult',
+        description: 'Consult synthetic industry experts grounded in PSFK trend graphs with citable analyst perspectives.',
+    },
+};
+app.get([
+    '/.well-known/mcp-server.json', '/.well-known/mcp',
+    '/.well-known/brand-intelligence', '/.well-known/brand-intelligence.json',
+    '/.well-known/topic-research', '/.well-known/topic-research.json',
+    '/.well-known/deep-research', '/.well-known/deep-research.json',
+    '/.well-known/earnings-intelligence', '/.well-known/earnings-intelligence.json',
+    '/.well-known/expert-consult', '/.well-known/expert-consult.json',
+], (req, res) => {
+    res.setHeader('Content-Type', 'application/json');
+    const matchedOffering = Object.keys(OFFERING_CARD_METADATA).find(slug => req.path.includes(slug));
+    if (matchedOffering && OFFERING_CARD_METADATA[matchedOffering]) {
+        const meta = OFFERING_CARD_METADATA[matchedOffering];
+        return res.json({
+            $schema: 'https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json',
+            name: meta.name,
+            title: meta.title,
+            description: meta.description,
+            websiteUrl: 'https://www.fodda.ai',
+            version: MCP_SERVER_VERSION,
+            capabilities: {
+                tools: { listChanged: false },
+                resources: { listChanged: false, subscribe: false },
+                prompts: { listChanged: false },
+            },
+            pricingTier: {
+                structure: 'free',
+                substance: 'metered',
+                tokenModel: 'Canonical token costs defined in API metering.ts ($0.50 via SPT / API credits)',
+            },
+            resourceSchemes: [
+                'fodda://expert/{slug}/insight/{id}',
+                'fodda://graph/{vertical}/trend/{slug}',
+            ],
+            endpoints: {
+                mcpStreamableHttp: `${getServiceUrl()}/${matchedOffering}`,
+                mcpSse: `${getServiceUrl()}/sse`,
+                telemetry: `${getServiceUrl()}/telemetry`,
+                feedback: `${getServiceUrl()}/v1/feedback`,
+            },
+        });
+    }
+    res.json({
+        $schema: 'https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json',
+        name: 'ai.fodda/mcp-server',
+        title: 'Fodda Knowledge Graphs',
+        description: 'Expert-curated knowledge, brand, research & earnings intelligence — 46 tools, 220+ graphs.',
+        websiteUrl: 'https://www.fodda.ai',
+        version: MCP_SERVER_VERSION,
+        capabilities: {
+            tools: { listChanged: false },
+            resources: { listChanged: false, subscribe: false },
+            prompts: { listChanged: false },
+        },
+        pricingTier: {
+            structure: 'free',
+            substance: 'metered',
+            tokenModel: 'Canonical token costs defined in API metering.ts ($0.50 via SPT / API credits)',
+        },
+        resourceSchemes: [
+            'fodda://expert/{slug}/insight/{id}',
+            'fodda://graph/{vertical}/trend/{slug}',
+        ],
+        endpoints: {
+            mcpStreamableHttp: `${getServiceUrl()}/mcp`,
+            mcpSse: `${getServiceUrl()}/sse`,
+            telemetry: `${getServiceUrl()}/telemetry`,
+            feedback: `${getServiceUrl()}/v1/feedback`,
+        },
+    });
+});
+// ---------------------------------------------------------------------------
+// Telemetry & Error-Rate Instrumentation Endpoints
+// ---------------------------------------------------------------------------
+app.get(['/telemetry', '/v1/telemetry'], (_req, res) => {
+    res.setHeader('Content-Type', 'application/json');
+    res.json(getTelemetryStats());
+});
+app.post('/v1/feedback', (req, res) => {
+    const { category, feedback, user_email, user } = req.body || {};
+    if (!feedback) {
+        return res.status(400).json({ error: 'Missing required field: feedback' });
+    }
+    const userLabel = user_email || user || 'anonymous HTTP user';
+    const catLabel = category || 'general';
+    recordFeedbackEntry(catLabel, feedback, userLabel);
+    res.json({ status: 'LOGGED', message: 'Feedback recorded successfully.' });
 });
 // ---------------------------------------------------------------------------
 // Widget cache — stores pre-rendered HTML for browser access
@@ -121,14 +332,8 @@ setInterval(() => {
 function getServiceUrl() {
     if (process.env.FODDA_SERVICE_URL)
         return process.env.FODDA_SERVICE_URL;
-    if (process.env.K_SERVICE) {
-        // Derive from K_SERVICE + K_REVISION if FODDA_SERVICE_URL not set.
-        // Requires CLOUD_RUN_REGION env var (e.g. 'uk') to be set.
-        const region = process.env.CLOUD_RUN_REGION || 'uk';
-        const revHash = process.env.K_REVISION?.split('-').pop();
-        if (!revHash)
-            console.error('[getServiceUrl] WARNING: K_REVISION not set — widget URLs may be wrong');
-        return `https://${process.env.K_SERVICE}-${revHash || 'unknown'}-${region}.a.run.app`;
+    if (process.env.NODE_ENV === 'production' || process.env.K_SERVICE) {
+        return 'https://mcp.fodda.ai';
     }
     return `http://localhost:${process.env.PORT || 8080}`;
 }
@@ -165,21 +370,26 @@ async function foddaRequest(method, path, apiKey, userId, body, requestId, sourc
     // HMAC sign the request
     const secret = process.env.FODDA_MCP_SECRET;
     if (secret) {
-        const payload = (method === 'POST' || method === 'PATCH') && body
-            ? timestamp + '.' + JSON.stringify(body)
+        const payload = (method === 'POST' || method === 'PATCH')
+            ? timestamp + '.' + JSON.stringify(body ?? {})
             : timestamp + '.' + path;
         const signature = crypto.createHmac('sha256', secret).update(payload).digest('hex');
         headers['X-Fodda-Signature'] = signature;
     }
-    const url = `${API_BASE_URL}${path}`;
+    const baseUrl = path.startsWith('/api/') ? WEBSITE_BASE_URL : API_BASE_URL;
+    const url = `${baseUrl}${path}`;
     // Base timeout: 30s aligns with MCP client expectations.
-    // Extended to 60s for analyst consult — multi-turn LLM + tool calls can legitimately exceed 30s.
-    const AXIOS_TIMEOUT_MS = /\/analysts\/consult/.test(path) ? 60000 : 30000;
+    // Extended to 60s for analyst consult, and 35s for supplemental.
+    const AXIOS_TIMEOUT_MS = /\/analysts\/consult/.test(path)
+        ? 60000
+        : /\/supplemental\//.test(path)
+            ? 35000
+            : 30000;
     const response = method === 'GET'
         ? await axios.get(url, { headers, timeout: AXIOS_TIMEOUT_MS })
         : method === 'PATCH'
-            ? await axios.patch(url, body, { headers, timeout: AXIOS_TIMEOUT_MS })
-            : await axios.post(url, body, { headers, timeout: AXIOS_TIMEOUT_MS });
+            ? await axios.patch(url, body ?? {}, { headers, timeout: AXIOS_TIMEOUT_MS })
+            : await axios.post(url, body ?? {}, { headers, timeout: AXIOS_TIMEOUT_MS });
     // ── Cache store ──
     cacheSet(method, path, body, response.data);
     // ── Inject upstream usage warning headers into response data ──
@@ -250,25 +460,95 @@ async function validateSpt(spt) {
 async function waverunnerRequest(interactionType, tokenCost, userApiKey, userId, waverunnerPayload) {
     // ── Pre-check credits ──
     // (sk_trial_ pre-check removed — new trial accounts are metered server-side by the API)
-    // ── Call Waverunner via Gemini SDK ──
-    const geminiKey = process.env.GEMINI_API_KEY;
+    // ── Call Waverunner via Gemini SDK (generateContent) ──
+    const geminiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_AI_API_KEY;
     if (!geminiKey) {
         throw new Error('GEMINI_API_KEY environment variable is required for Waverunner calls.');
     }
     const { GoogleGenAI } = await import('@google/genai');
     const ai = new GoogleGenAI({ apiKey: geminiKey });
-    const result = await ai.interactions.create(waverunnerPayload);
+    const model = waverunnerPayload.model || 'gemini-2.5-flash';
+    const systemInstruction = waverunnerPayload.system_instruction;
+    const inputParts = Array.isArray(waverunnerPayload.input)
+        ? waverunnerPayload.input.map((i) => i.text || '').filter(Boolean).join('\n\n')
+        : (typeof waverunnerPayload.input === 'string' ? waverunnerPayload.input : (waverunnerPayload.prompt || ''));
+    const config = {};
+    if (systemInstruction) {
+        config.systemInstruction = systemInstruction;
+    }
+    if (waverunnerPayload.response_mime_type || waverunnerPayload.responseMimeType) {
+        config.responseMimeType = waverunnerPayload.response_mime_type || waverunnerPayload.responseMimeType;
+    }
+    if (Array.isArray(waverunnerPayload.tools) && waverunnerPayload.tools.length > 0) {
+        const toolsMapped = [];
+        let googleSearchAdded = false;
+        let urlContextAdded = false;
+        for (const t of waverunnerPayload.tools) {
+            if (t.type === 'url_context') {
+                // urlContext retrieves the page itself. It must NOT collapse into
+                // googleSearch — search cannot fetch a specific URL, which left
+                // read_url asking the model to extract a page it had no way to
+                // read, so it answered with a refusal instead of content.
+                if (!urlContextAdded) {
+                    toolsMapped.push({ urlContext: {} });
+                    urlContextAdded = true;
+                }
+            }
+            else if (t.type === 'google_search') {
+                if (!googleSearchAdded) {
+                    toolsMapped.push({ googleSearch: {} });
+                    googleSearchAdded = true;
+                }
+            }
+            else {
+                toolsMapped.push(t);
+            }
+        }
+        if (toolsMapped.length > 0) {
+            config.tools = toolsMapped;
+        }
+    }
+    const generatePromise = ai.models.generateContent({
+        model,
+        contents: [
+            {
+                role: 'user',
+                parts: [{ text: inputParts }]
+            }
+        ],
+        config
+    });
+    let timeoutTimer;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutTimer = setTimeout(() => reject(new Error('Gemini model generation timed out after 180 seconds.')), 180000);
+    });
+    let response;
+    try {
+        response = await Promise.race([generatePromise, timeoutPromise]);
+    }
+    finally {
+        clearTimeout(timeoutTimer);
+    }
+    const reportText = response.text || '';
+    const groundingChunks = response.candidates?.[0]?.groundingMetadata?.groundingChunks || [];
+    // Surfaced so URL-reading callers can distinguish "page fetched" from a
+    // model refusal — a refusal is non-empty text and otherwise looks like success.
+    const urlContextMetadata = response.candidates?.[0]?.urlContextMetadata || null;
     // ── Post-decrement (paid accounts) ──
     foddaRequest('POST', '/v1/research/meter', userApiKey, userId, {
         type: interactionType,
         billable_units: tokenCost,
     }).catch(err => console.error('[waverunnerRequest] Metering failed:', err.message));
-    return result;
+    return {
+        outputs: [{ type: 'text', text: reportText }],
+        groundingMetadata: { groundingChunks },
+        urlContextMetadata
+    };
 }
 // ---------------------------------------------------------------------------
 // Browser Landing Page — catch humans who paste the MCP URL into a browser
 // ---------------------------------------------------------------------------
-app.get('/mcp', (req, res, next) => {
+app.get(['/mcp', '/brand-intelligence', '/topic-research', '/deep-research', '/earnings-intelligence', '/expert-consult'], (req, res, next) => {
     // Only intercept browser requests (Accept: text/html).
     // MCP SDK clients send application/json or text/event-stream, so they
     // fall through to the app.all('/mcp') transport handler below.
@@ -518,13 +798,58 @@ app.get('/mcp', (req, res, next) => {
 </body>
 </html>`);
 });
+const tokenCache = new Map();
+const TOKEN_CACHE_TTL_MS = 60 * 1000; // 1 minute TTL
+export async function resolveMcpToken(token, websiteBaseUrl) {
+    const cached = tokenCache.get(token);
+    if (cached && (Date.now() - cached.fetchedAt < TOKEN_CACHE_TTL_MS)) {
+        return cached;
+    }
+    const secret = process.env.FODDA_MCP_SECRET || process.env.ONBOARD_SECRET || '';
+    if (!secret) {
+        console.warn('[token-resolver] Neither FODDA_MCP_SECRET nor ONBOARD_SECRET is set in environment; sending token resolution request without X-Fodda-Mcp-Secret header.');
+    }
+    const headers = {};
+    if (secret) {
+        headers['X-Fodda-Mcp-Secret'] = secret;
+    }
+    try {
+        const response = await axios.get(`${websiteBaseUrl}/api/mcp-tokens/${token}`, {
+            headers,
+            timeout: 5000,
+        });
+        const data = response.data;
+        if (!data.apiKey || !data.email) {
+            throw new Error('Invalid token resolution payload');
+        }
+        const val = {
+            apiKey: data.apiKey,
+            email: data.email,
+            name: data.name || '',
+            analystId: data.analystId || '',
+            fetchedAt: Date.now()
+        };
+        tokenCache.set(token, val);
+        return val;
+    }
+    catch (err) {
+        if (axios.isAxiosError(err) && err.response && (err.response.status === 401 || err.response.status === 403)) {
+            throw new Error(`Token resolution request unauthorized (HTTP ${err.response.status}). Check FODDA_MCP_SECRET / ONBOARD_SECRET configuration.`);
+        }
+        throw err;
+    }
+}
 // ---------------------------------------------------------------------------
 // MCP Transport Handler
 // ---------------------------------------------------------------------------
-app.all('/mcp', async (req, res) => {
+app.all(['/mcp', '/brand-intelligence', '/topic-research', '/deep-research', '/earnings-intelligence', '/expert-consult', '/c/:token'], async (req, res) => {
     try {
         const sessionId = req.headers['mcp-session-id'];
         let transport;
+        // Determine offering slug and tool filtering from URL path
+        const rawPath = req.path || '';
+        const offeringSlug = (rawPath.replace(/^\//, '').split('/')[0] || '');
+        const allowedTools = OFFERING_SCOPED_TOOLS[offeringSlug];
         // SPT (anonymous Shared Payment Token) detection — MUST precede api-key
         // extraction so an `spt_xxx` Bearer is never treated as an API key.
         const rawAuth = req.headers['authorization']?.toString() || '';
@@ -533,30 +858,116 @@ app.all('/mcp', async (req, res) => {
             || (/^Bearer\s+spt_/i.test(rawAuth) ? rawAuth.replace(/^Bearer\s+/i, '') : '')
             || '';
         const isSpt = !!spt;
-        // Extract API key, userId, and entry ID from URL or headers
-        // Priority: query string (existing MCP clients) → X-API-Key header → Authorization Bearer (Remote MCP)
-        const apiKey = isSpt ? '' : (req.query.api_key
+        const rawBearer = !isSpt ? rawAuth.replace(/^Bearer\s+/i, '').trim() : '';
+        // Clerk OAuth tokens may be JWTs (eyJ...), opaque tokens (oat_...), session tokens (sess_...), or custom OAuth tokens.
+        // If it's not a standard sk_live_ / sk_trial_ key, send it to clerk-resolve.
+        const isClerkJwt = !isSpt && rawBearer.length > 0 && !rawBearer.startsWith('sk_live_') && !rawBearer.startsWith('sk_trial_');
+        if (isClerkJwt) {
+            // Attempt Clerk JWT → Fodda API key resolution
+            try {
+                const resolveUrl = `${API_BASE_URL}/v1/auth/clerk-resolve`;
+                const resolveResp = await axios.post(resolveUrl, { clerk_jwt: rawBearer }, {
+                    headers: { 'X-Internal-Key': process.env.FODDA_INTERNAL_API_KEY || '' },
+                    timeout: 5000,
+                });
+                if (resolveResp.data?.api_key) {
+                    req.__resolvedApiKey = resolveResp.data.api_key;
+                    req.__resolvedUserId = resolveResp.data.user_id || 'oauth_user';
+                }
+                else {
+                    return res.status(401).json({
+                        jsonrpc: '2.0',
+                        error: { code: -32000, message: 'OAuth token could not be resolved to a Fodda account. Visit https://app.fodda.ai to reconnect.' },
+                        id: (req.body && typeof req.body === 'object' && 'id' in req.body) ? req.body.id : null,
+                    });
+                }
+            }
+            catch (clerkErr) {
+                const status = clerkErr.response?.status;
+                if (status === 404 || status === 501) {
+                    return res.status(501).json({
+                        jsonrpc: '2.0',
+                        error: { code: -32000, message: 'OAuth token resolution is not yet available on this server. Please use header API key auth (Authorization: Bearer sk_live_...) from https://app.fodda.ai.' },
+                        id: (req.body && typeof req.body === 'object' && 'id' in req.body) ? req.body.id : null,
+                    });
+                }
+                return res.status(401).json({
+                    jsonrpc: '2.0',
+                    error: { code: -32000, message: 'OAuth token validation failed. Please reconnect at https://app.fodda.ai.' },
+                    id: (req.body && typeof req.body === 'object' && 'id' in req.body) ? req.body.id : null,
+                });
+            }
+        }
+        const token = req.params.token;
+        let resolvedApiKey = '';
+        let resolvedEmail = '';
+        let resolvedEntryId = '';
+        if (token) {
+            try {
+                const resolved = await resolveMcpToken(token, WEBSITE_BASE_URL);
+                resolvedApiKey = resolved.apiKey;
+                resolvedEmail = resolved.email;
+                resolvedEntryId = resolved.analystId;
+            }
+            catch (err) {
+                console.error(`[token-resolver] Failed to resolve connection token:`, err.message);
+                return res.status(401).json({ error: 'Invalid or expired connection token' });
+            }
+        }
+        // Extract API key, userId, and entry ID from URL or headers.
+        // Priority: resolved OAuth key → X-API-Key header → Authorization Bearer (if non-Clerk) → resolved token key → query string (fallback).
+        const resolvedOAuthKey = req.__resolvedApiKey || '';
+        const resolvedOAuthUser = req.__resolvedUserId || '';
+        const apiKey = isSpt ? '' : (resolvedOAuthKey
             || req.headers['x-api-key']
-            || (req.headers['authorization']?.toString().replace(/^Bearer\s+/i, ''))
+            || (!isClerkJwt ? (req.headers['authorization']?.toString().replace(/^Bearer\s+/i, '')) : '')
+            || resolvedApiKey
+            || req.query.api_key
             || '');
-        const entryId = req.query.id || '';
+        const entryId = resolvedEntryId || req.query.id || '';
         // If id looks like an email and no explicit user_id, use it as userId for tracking + signup
         const isEmailId = entryId.includes('@') && entryId.includes('.');
-        const userId = isSpt ? 'spt_agent' : (req.query.user_id
+        // Priority for userId: resolved OAuth user → resolved token email → query user_id → header X-User-Id → query id / anonymous
+        const userId = isSpt ? 'spt_agent' : (resolvedOAuthUser
+            || resolvedEmail
+            || req.query.user_id
             || req.headers['x-user-id']
             || (isEmailId ? entryId : 'anonymous'));
-        const source = req.query.source || (isSpt ? 'spt' : '');
+        const defaultSource = (offeringSlug !== 'mcp' && allowedTools !== undefined) ? offeringSlug : (isSpt ? 'spt' : '');
+        const source = req.query.source || defaultSource;
         if (sessionId && transports.has(sessionId)) {
             transport = transports.get(sessionId);
         }
         else if (!sessionId && req.method === 'POST') {
             const body = req.body;
             if (body?.method === 'initialize') {
+                // Directory connector policy: /mcp requires authentication — Clerk OAuth,
+                // an API key, or a /c/<token> connection URL. An anonymous handshake gets
+                // 401 + WWW-Authenticate (RFC 9728) so MCP clients auto-start the OAuth
+                // flow. Set MCP_ALLOW_ANONYMOUS=true to re-open the anonymous trial lane.
+                if (offeringSlug === 'mcp' && !isSpt && !apiKey && process.env.MCP_ALLOW_ANONYMOUS !== 'true') {
+                    res.setHeader('WWW-Authenticate', 'Bearer resource_metadata="https://mcp.fodda.ai/.well-known/oauth-protected-resource/mcp"');
+                    return res.status(401).json({
+                        jsonrpc: '2.0',
+                        error: { code: -32000, message: 'Authentication required. Connect via OAuth, or use your personal connection URL or API key from https://app.fodda.ai.' },
+                        id: body?.id ?? null,
+                    });
+                }
                 // For an SPT (anonymous) session: validate the token ONCE now (no charge)
                 // so we can refuse a task the SPT can't cover before running it. Reject the
                 // connection if the token is bad/unfunded.
+                //
+                // Directory connector policy: SPT lane is disabled on this endpoint when
+                // ENABLE_SPT !== 'true'. The listed connector is OAuth + account credits only.
                 let sptInfo = null;
                 if (isSpt) {
+                    if (process.env.ENABLE_SPT !== 'true') {
+                        return res.status(401).json({
+                            jsonrpc: '2.0',
+                            error: { code: -32000, message: 'SPT payment tokens are not accepted on this endpoint. Connect via OAuth at https://app.fodda.ai.' },
+                            id: body?.id ?? null,
+                        });
+                    }
                     const v = await validateSpt(spt);
                     if (!v.valid) {
                         return res.status(402).json({
@@ -576,7 +987,7 @@ app.all('/mcp', async (req, res) => {
                     : (source
                         ? ((m, p, k, u, b, r) => foddaRequest(m, p, k, u, b, r, source))
                         : foddaRequest);
-                const server = await createServer(apiKey, userId, boundFoddaRequest, waverunnerRequest, storeWidget, getServiceUrl, entryId, sptInfo ?? undefined);
+                const server = await createServer(apiKey, userId, boundFoddaRequest, waverunnerRequest, storeWidget, getServiceUrl, entryId, sptInfo ?? undefined, allowedTools);
                 transport = new StreamableHTTPServerTransport({
                     sessionIdGenerator: () => crypto.randomUUID(),
                     onsessioninitialized: (sid) => {
@@ -685,7 +1096,9 @@ app.get('/health', (_req, res) => res.json({ status: 'ok', version: MCP_SERVER_V
 // ---------------------------------------------------------------------------
 // A2A Protocol Endpoint — agent-to-agent task delegation
 // ---------------------------------------------------------------------------
-registerA2ARoute(app, foddaRequest);
+registerA2ARoute(app, foddaRequest, waverunnerRequest);
+// AgentFacts (NANDA) identity document — projection of the A2A card + version
+registerAgentFactsRoute(app, getServiceUrl);
 const PORT = parseInt(process.env.PORT || '8080');
 // Initialize catalog and pricing caches before accepting connections
 Promise.all([