@smartbear/mcp 0.10.0 → 0.11.0

package/dist/common/transport-http.js

@@ -0,0 +1,377 @@
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { clientRegistry } from "./client-registry.js";
+import { SmartBearMcpServer } from "./server.js";
+/**
+ * Run server in HTTP mode with Streamable HTTP transport
+ * Supports both SSE (legacy) and StreamableHTTP transports for backwards compatibility
+ */
+export async function runHttpMode() {
+    const PORT = process.env.PORT ? Number.parseInt(process.env.PORT, 10) : 3000;
+    const allowedOrigins = process.env.ALLOWED_ORIGINS?.split(",") || [
+        "http://localhost:3000",
+    ];
+    // Store transports by session ID
+    const transports = new Map();
+    // Get dynamic list of allowed headers from registered clients
+    const allowedAuthHeaders = getHttpHeaders();
+    const allowedHeaders = [
+        "Content-Type",
+        "Authorization",
+        "MCP-Session-Id", // Required for StreamableHTTP
+        "x-custom-auth-headers", // used by mcp-inspector
+        ...allowedAuthHeaders,
+    ].join(", ");
+    const httpServer = createServer(async (req, res) => {
+        // Enable CORS
+        const origin = req.headers.origin || "";
+        if (allowedOrigins.includes(origin)) {
+            res.setHeader("Access-Control-Allow-Origin", origin);
+        }
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", allowedHeaders);
+        res.setHeader("Access-Control-Expose-Headers", "MCP-Session-Id");
+        if (req.method === "OPTIONS") {
+            res.writeHead(200);
+            res.end();
+            return;
+        }
+        const url = new URL(req.url || "/", `http://${req.headers.host}`);
+        // HEALTH CHECK ENDPOINT
+        if (req.method === "GET" && url.pathname === "/health") {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ status: "ok", timestamp: new Date().toISOString() }));
+            return;
+        }
+        // STREAMABLE HTTP ENDPOINT (modern, preferred)
+        if (url.pathname === "/mcp") {
+            await handleStreamableHttpRequest(req, res, transports);
+            return;
+        }
+        // LEGACY SSE ENDPOINT (for backwards compatibility)
+        if (req.method === "GET" && url.pathname === "/sse") {
+            await handleLegacySseRequest(req, res, transports);
+            return;
+        }
+        if (req.method === "POST" && url.pathname === "/message") {
+            await handleLegacyMessageRequest(req, res, url, transports);
+            return;
+        }
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Not found");
+    });
+    httpServer.listen(PORT, () => {
+        console.log(`[MCP HTTP Server] Listening on http://localhost:${PORT}`);
+        console.log(`[MCP HTTP Server] Health check: http://localhost:${PORT}/health`);
+        console.log(`[MCP HTTP Server] Modern endpoint: http://localhost:${PORT}/mcp (Streamable HTTP)`);
+        console.log(`[MCP HTTP Server] Legacy endpoint: http://localhost:${PORT}/sse (SSE)`);
+        const headerHelp = getHttpHeadersHelp();
+        if (headerHelp.length > 0) {
+            console.log(`[MCP HTTP Server] Send configuration headers:\n${headerHelp.join("\n")}`);
+        }
+        else {
+            console.warn(`[MCP HTTP Server] No clients support HTTP header configuration`);
+        }
+    });
+}
+/**
+ * Parse request body for POST requests
+ * Reads the request stream and parses it as JSON
+ * @returns Parsed JSON object or undefined if not a POST request or parsing fails
+ */
+async function parseRequestBody(req) {
+    if (req.method !== "POST") {
+        return undefined;
+    }
+    let body = "";
+    req.on("data", (chunk) => {
+        body += chunk.toString();
+    });
+    return new Promise((resolve) => {
+        req.on("end", () => {
+            try {
+                resolve(JSON.parse(body));
+            }
+            catch (error) {
+                console.error("Error parsing request body:", error);
+                resolve(undefined);
+            }
+        });
+    });
+}
+/**
+ * Get existing transport for session or return error response
+ * Validates that the session exists and uses StreamableHTTP transport
+ * @returns StreamableHTTPServerTransport if valid, null otherwise (with error response sent)
+ */
+function getExistingTransport(sessionId, transports, res) {
+    const existing = transports.get(sessionId);
+    if (existing && existing.transport instanceof StreamableHTTPServerTransport) {
+        return existing.transport;
+    }
+    // Session doesn't exist or is using a different transport (e.g., SSE)
+    res.writeHead(400, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({
+        jsonrpc: "2.0",
+        error: {
+            code: -32000,
+            message: "Bad Request: Session exists but uses a different transport protocol",
+        },
+        id: null,
+    }));
+    return null;
+}
+/**
+ * Create new transport for initialize request
+ * Sets up a new MCP server instance with configuration from HTTP headers,
+ * creates a StreamableHTTP transport, and registers session lifecycle handlers
+ * @returns StreamableHTTPServerTransport if successful, null if server initialization fails
+ */
+async function createNewTransport(req, res, transports) {
+    // Create and configure server with headers from the request
+    const server = await newServer(req, res);
+    if (!server) {
+        return null;
+    }
+    // Create transport with session management
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+        onsessioninitialized: (newSessionId) => {
+            console.log(`[MCP] New session initialized: ${newSessionId}`);
+            // Store session so subsequent requests can find it
+            transports.set(newSessionId, { server, transport });
+        },
+    });
+    // Clean up session on close
+    transport.onclose = () => {
+        if (transport.sessionId) {
+            console.log(`[MCP] Session closed: ${transport.sessionId}`);
+            transports.delete(transport.sessionId);
+        }
+    };
+    // Connect server to transport to start handling messages
+    await server.connect(transport);
+    return transport;
+}
+/**
+ * Handle modern Streamable HTTP requests
+ * This is the main endpoint (/mcp) for the modern MCP StreamableHTTP transport.
+ *
+ * Request flow:
+ * 1. First request (initialize): No session ID, body contains initialize request
+ *    - Creates new server + transport, generates session ID
+ * 2. Subsequent requests: Include MCP-Session-Id header
+ *    - Routes to existing transport for the session
+ */
+async function handleStreamableHttpRequest(req, res, transports) {
+    try {
+        const sessionId = req.headers["mcp-session-id"];
+        const parsedBody = await parseRequestBody(req);
+        let transport;
+        // Case 1: Existing session - route to existing transport
+        if (sessionId && transports.has(sessionId)) {
+            const existingTransport = getExistingTransport(sessionId, transports, res);
+            if (!existingTransport)
+                return;
+            transport = existingTransport;
+        }
+        // Case 2: New session - must be an initialize request
+        else if (!sessionId &&
+            req.method === "POST" &&
+            parsedBody &&
+            isInitializeRequest(parsedBody)) {
+            const newTransport = await createNewTransport(req, res, transports);
+            if (!newTransport)
+                return;
+            transport = newTransport;
+        }
+        // Case 3: Invalid request
+        else {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                jsonrpc: "2.0",
+                error: {
+                    code: -32000,
+                    message: "Bad Request: Invalid request",
+                },
+                id: null,
+            }));
+            return;
+        }
+        // Delegate to transport to handle the MCP protocol message
+        await transport.handleRequest(req, res, parsedBody);
+    }
+    catch (error) {
+        console.error("Error handling StreamableHTTP request:", error);
+        res.writeHead(500, { "Content-Type": "text/plain" });
+        res.end("Internal server error");
+    }
+}
+/**
+ * Handle legacy SSE connection requests (GET /sse)
+ *
+ * SSE (Server-Sent Events) transport maintains a long-lived connection
+ * for server-to-client messages, with a separate POST endpoint for client-to-server.
+ *
+ * This is kept for backwards compatibility with older MCP clients.
+ * New integrations should use the modern StreamableHTTP transport (/mcp).
+ */
+async function handleLegacySseRequest(req, res, transports) {
+    // Create a new server instance for this connection
+    const server = await newServer(req, res);
+    if (!server) {
+        return;
+    }
+    // SSE transport keeps the connection open and sends events to the client
+    const transport = new SSEServerTransport("/message", res);
+    // Store the session so POST /message requests can find it
+    transports.set(transport.sessionId, { server, transport });
+    // Clean up session when connection closes
+    res.on("close", () => {
+        transports.delete(transport.sessionId);
+    });
+    // Connect server to transport (this also starts the transport automatically)
+    await server.connect(transport);
+}
+/**
+ * Handle legacy POST message requests (POST /message?sessionId=xxx)
+ *
+ * This endpoint is part of the legacy SSE transport, handling client-to-server messages.
+ * The SSE transport uses:
+ * - GET /sse: Server-to-client events (long-lived connection)
+ * - POST /message: Client-to-server messages (individual requests)
+ *
+ * New integrations should use the modern StreamableHTTP transport (/mcp).
+ */
+async function handleLegacyMessageRequest(req, res, url, transports) {
+    // Extract session ID from query parameter
+    const sessionId = url.searchParams.get("sessionId");
+    if (!sessionId) {
+        res.writeHead(400, { "Content-Type": "text/plain" });
+        res.end("Missing sessionId parameter");
+        return;
+    }
+    // Find the session created by the SSE connection
+    const session = transports.get(sessionId);
+    if (!session) {
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Session not found");
+        return;
+    }
+    // Validate this session is using SSE transport
+    if (!(session.transport instanceof SSEServerTransport)) {
+        res.writeHead(400, { "Content-Type": "text/plain" });
+        res.end("Invalid transport for this endpoint");
+        return;
+    }
+    // Read and parse the request body
+    let body = "";
+    req.on("data", (chunk) => {
+        body += chunk.toString();
+    });
+    req.on("end", async () => {
+        try {
+            const parsedBody = JSON.parse(body);
+            // Route message to the SSE transport for processing
+            await session.transport.handlePostMessage(req, res, parsedBody);
+        }
+        catch (error) {
+            console.error("Error handling POST message:", error);
+            res.writeHead(500, { "Content-Type": "text/plain" });
+            res.end("Internal server error");
+        }
+    });
+}
+/**
+ * Create a new MCP server instance with configuration from HTTP headers
+ *
+ * Configuration is read from HTTP headers in the format:
+ * {ClientPrefix}-{Field-Name} (e.g., Bugsnag-Auth-Token, Reflect-Api-Token)
+ *
+ * The ClientRegistry validates the configuration and initializes enabled clients.
+ * If configuration fails, an error response is sent and null is returned.
+ *
+ * @returns SmartBearMcpServer instance if successful, null if configuration fails
+ */
+async function newServer(req, res) {
+    const server = new SmartBearMcpServer();
+    try {
+        // Configure server with values from HTTP headers
+        await clientRegistry.configure(server, (client, key) => {
+            const headerName = getHeaderName(client, key);
+            // Check both original case and lower-case headers for compatibility
+            // (HTTP headers are case-insensitive, but Node.js lowercases them)
+            const value = req.headers[headerName] || req.headers[headerName.toLowerCase()];
+            if (typeof value === "string") {
+                return value;
+            }
+            return null;
+        });
+    }
+    catch (error) {
+        // Configuration failed - provide helpful error message
+        const headerHelp = getHttpHeadersHelp();
+        const errorMessage = headerHelp.length > 0
+            ? `Configuration error: ${error instanceof Error ? error.message : String(error)}. Please provide valid headers:\n${headerHelp.join("\n")}`
+            : "No clients support HTTP header configuration.";
+        res.writeHead(401, { "Content-Type": "text/plain" });
+        res.end(errorMessage);
+        return null;
+    }
+    return server;
+}
+/**
+ * Convert a config key to HTTP header name format
+ *
+ * Examples:
+ * - auth_token -> Auth-Token
+ * - project_api_key -> Project-Api-Key
+ * - base_url -> Base-Url
+ *
+ * Combined with configPrefix: Bugsnag-Auth-Token, Reflect-Api-Token, etc.
+ *
+ * @param client The client instance (provides configPrefix)
+ * @param key The config key in snake_case
+ * @returns Header name in format: {ConfigPrefix}-{Pascal-Kebab-Case}
+ */
+function getHeaderName(client, key) {
+    return `${client.configPrefix}-${key
+        .split("_")
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+        .join("-")}`;
+}
+/**
+ * Get all HTTP headers that clients support for authentication
+ * Returns a list of header names (in kebab-case) that should be allowed
+ */
+function getHttpHeaders() {
+    const headers = new Set();
+    // Use getAll() to respect MCP_ENABLED_CLIENTS filtering
+    for (const entry of clientRegistry.getAll()) {
+        for (const configKey of Object.keys(entry.config.shape)) {
+            headers.add(getHeaderName(entry, configKey));
+        }
+    }
+    return Array.from(headers).sort((a, b) => a.localeCompare(b));
+}
+/**
+ * Get human-readable list of HTTP headers for logging/error messages
+ * Organized by client
+ */
+function getHttpHeadersHelp() {
+    const messages = [];
+    for (const entry of clientRegistry.getAll()) {
+        messages.push(` - ${entry.name}:`);
+        for (const [configKey, requirement] of Object.entries(entry.config.shape)) {
+            const headerName = getHeaderName(entry, configKey);
+            const requiredTag = requirement.isOptional()
+                ? " (optional)"
+                : " (required)";
+            messages.push(`    - ${headerName}${requiredTag}: ${requirement.description}`);
+        }
+    }
+    return messages;
+}

package/dist/common/transport-stdio.js

@@ -0,0 +1,43 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { clientRegistry } from "./client-registry.js";
+import { SmartBearMcpServer } from "./server.js";
+/**
+ * Generate a dynamic error message listing all available clients and their required env vars
+ */
+function getNoConfigErrorMessage() {
+    const messages = [];
+    for (const entry of clientRegistry.getAll()) {
+        messages.push(` - ${entry.name}:`);
+        for (const [configKey, requirement] of Object.entries(entry.config.shape)) {
+            const envVarName = getEnvVarName(entry, configKey);
+            const requiredTag = requirement.isOptional()
+                ? " (optional)"
+                : " (required)";
+            messages.push(`    - ${envVarName}${requiredTag}: ${requirement.description}`);
+        }
+    }
+    return messages;
+}
+/**
+ * Run server in STDIO mode (default)
+ */
+export async function runStdioMode() {
+    const server = new SmartBearMcpServer();
+    // Setup clients from environment variables
+    const configuredCount = await clientRegistry.configure(server, (client, key) => {
+        const envVarName = getEnvVarName(client, key);
+        return process.env[envVarName] || null;
+    });
+    if (configuredCount === 0) {
+        const errorMessage = getNoConfigErrorMessage();
+        console.error(errorMessage.length > 0
+            ? `No clients configured. Please provide valid environment variables for at least one client:\n${errorMessage.join("\n")}`
+            : "No clients support environment variable configuration.");
+        process.exit(1);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+function getEnvVarName(client, key) {
+    return `${client.configPrefix.toUpperCase().replace(/-/g, "_")}_${key.toUpperCase()}`;
+}

package/dist/index.js

@@ -1,14 +1,8 @@
 #!/usr/bin/env node
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { ApiHubClient } from "./api-hub/client.js";
-import { BugsnagClient } from "./bugsnag/client.js";
-import { CollaboratorClient } from "./collaborator/client.js";
 import Bugsnag from "./common/bugsnag.js";
-import { SmartBearMcpServer } from "./common/server.js";
-import { PactflowClient } from "./pactflow/client.js";
-import { QmetryClient } from "./qmetry/client.js";
-import { ReflectClient } from "./reflect/client.js";
-import { ZephyrClient } from "./zephyr/client.js";
+import "./common/register-clients.js"; // Register all available clients
+import { runHttpMode } from "./common/transport-http.js";
+import { runStdioMode } from "./common/transport-stdio.js";
 // This is used to report errors in the MCP server itself
 // If you want to use your own BugSnag API key, set the MCP_SERVER_BUGSNAG_API_KEY environment variable
 const McpServerBugsnagAPIKey = process.env.MCP_SERVER_BUGSNAG_API_KEY;
@@ -16,69 +10,25 @@ if (McpServerBugsnagAPIKey) {
     Bugsnag.start(McpServerBugsnagAPIKey);
 }
 async function main() {
-    const server = new SmartBearMcpServer();
-    const reflectToken = process.env.REFLECT_API_TOKEN;
-    const bugsnagToken = process.env.BUGSNAG_AUTH_TOKEN;
-    const apiHubToken = process.env.API_HUB_API_KEY;
-    const pactBrokerToken = process.env.PACT_BROKER_TOKEN;
-    const pactBrokerUrl = process.env.PACT_BROKER_BASE_URL;
-    const pactBrokerUsername = process.env.PACT_BROKER_USERNAME;
-    const pactBrokerPassword = process.env.PACT_BROKER_PASSWORD;
-    const qmetryToken = process.env.QMETRY_API_KEY;
-    const qmetryBaseUrl = process.env.QMETRY_BASE_URL;
-    const zephyrToken = process.env.ZEPHYR_API_TOKEN;
-    const zephyrBaseUrl = process.env.ZEPHYR_BASE_URL;
-    const collaboratorBaseUrl = process.env.COLLAB_BASE_URL;
-    const collaboratorUsername = process.env.COLLAB_USERNAME;
-    const collaboratorLoginTicket = process.env.COLLAB_LOGIN_TICKET;
-    let client_defined = false;
-    if (reflectToken) {
-        server.addClient(new ReflectClient(reflectToken));
-        client_defined = true;
-    }
-    if (bugsnagToken) {
-        const bugsnagClient = new BugsnagClient(bugsnagToken, process.env.BUGSNAG_PROJECT_API_KEY, process.env.BUGSNAG_ENDPOINT);
-        await bugsnagClient.initialize();
-        server.addClient(bugsnagClient);
-        client_defined = true;
-    }
-    if (apiHubToken) {
-        server.addClient(new ApiHubClient(apiHubToken));
-        client_defined = true;
-    }
-    if (pactBrokerUrl) {
-        if (pactBrokerToken) {
-            server.addClient(new PactflowClient(pactBrokerToken, pactBrokerUrl, "pactflow", server.server));
-            client_defined = true;
-        }
-        else if (pactBrokerUsername && pactBrokerPassword) {
-            server.addClient(new PactflowClient({ username: pactBrokerUsername, password: pactBrokerPassword }, pactBrokerUrl, "pact_broker", server.server));
-            client_defined = true;
-        }
-        else {
-            console.error("If the Pact Broker base URL is specified, you must specify either (a) a PactFlow token, or (b) a Pact Broker username and password pair.");
-        }
-    }
-    if (qmetryToken) {
-        server.addClient(new QmetryClient(qmetryToken, qmetryBaseUrl));
-        client_defined = true;
-    }
-    if (zephyrToken) {
-        server.addClient(new ZephyrClient(zephyrToken, zephyrBaseUrl));
-        client_defined = true;
-    }
-    if (collaboratorBaseUrl && collaboratorUsername && collaboratorLoginTicket) {
-        server.addClient(new CollaboratorClient(collaboratorBaseUrl, collaboratorUsername, collaboratorLoginTicket));
-        client_defined = true;
-    }
-    if (!client_defined) {
-        console.error("No SmartBear products were configured. Please provide at least one of the required configuration options.");
+    // Determine transport mode from environment variable
+    // MCP_TRANSPORT can be "stdio" (default) or "http"
+    const transportMode = process.env.MCP_TRANSPORT?.toLowerCase() || "stdio";
+    if (transportMode === "http") {
+        console.log("[MCP] Starting in HTTP mode...");
+        await runHttpMode();
+    }
+    else if (transportMode === "stdio") {
+        await runStdioMode();
+    }
+    else {
+        console.error(`[MCP] Invalid transport mode: ${transportMode}. Use "stdio" or "http".`);
         process.exit(1);
     }
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
 }
-main().catch((error) => {
+try {
+    await main();
+}
+catch (error) {
     console.error("Fatal error in main():", error);
     process.exit(1);
-});
+}

package/dist/pactflow/client.js

@@ -1,46 +1,66 @@
+import z from "zod";
 import { MCP_SERVER_NAME, MCP_SERVER_VERSION } from "../common/info.js";
 import { ToolError, } from "../common/types.js";
 import { getOADMatcherRecommendations, getUserMatcherSelection, } from "./client/prompt-utils.js";
 import { PROMPTS } from "./client/prompts.js";
 import { TOOLS } from "./client/tools.js";
+const ConfigurationSchema = z.object({
+    base_url: z.string().url().describe("Pact Broker or PactFlow base URL"),
+    token: z
+        .string()
+        .optional()
+        .describe("Bearer token for PactFlow authentication (use this OR username/password)"),
+    username: z.string().optional().describe("Username for Pact Broker"),
+    password: z.string().optional().describe("Password for Pact Broker"),
+});
 // Tool definitions for PactFlow AI API client
 export class PactflowClient {
     name = "Contract Testing";
-    prefix = "contract-testing";
+    toolPrefix = "contract-testing";
+    configPrefix = "Pact-Broker";
+    config = ConfigurationSchema;
     headers;
     aiBaseUrl;
     baseUrl;
-    clientType;
-    server;
-    /**
-     * Creates an instance of the PactflowClient.
-     *
-     * @param auth The authentication token or credentials.
-     * @param baseUrl The base URL for the API.
-     * @param clientType The type of client (e.g., PactFlow, Pact Broker).
-     * @param server The SmartBear MCP server instance.
-     */
-    constructor(auth, baseUrl, clientType, server) {
+    _clientType;
+    _server;
+    get server() {
+        if (!this._server)
+            throw new Error("Server not configured");
+        return this._server;
+    }
+    get clientType() {
+        if (!this._clientType)
+            throw new Error("Client not configured");
+        return this._clientType;
+    }
+    async configure(server, config) {
         // Set headers based on the type of auth provided
-        if (typeof auth === "string") {
+        if (typeof config.token === "string") {
             this.headers = {
-                Authorization: `Bearer ${auth}`,
+                Authorization: `Bearer ${config.token}`,
                 "Content-Type": "application/json",
                 "User-Agent": `${MCP_SERVER_NAME}/${MCP_SERVER_VERSION}`,
             };
+            this._clientType = "pactflow";
         }
-        else {
-            const authString = `${auth.username}:${auth.password}`;
+        else if (typeof config.username === "string" &&
+            typeof config.password === "string") {
+            const authString = `${config.username}:${config.password}`;
             this.headers = {
                 Authorization: `Basic ${Buffer.from(authString).toString("base64")}`,
                 "Content-Type": "application/json",
                 "User-Agent": `${MCP_SERVER_NAME}/${MCP_SERVER_VERSION}`,
             };
+            this._clientType = "pact_broker";
+        }
+        else {
+            return false; // Don't configure the client if no auth is provided
         }
-        this.baseUrl = baseUrl;
+        this.baseUrl = config.base_url;
         this.aiBaseUrl = `${this.baseUrl}/api/ai`;
-        this.clientType = clientType;
-        this.server = server;
+        this._server = server.server;
+        return true;
     }
     // PactFlow AI client methods
     /**

package/dist/qmetry/client.js

@@ -1,20 +1,35 @@
+import z from "zod";
 import { autoResolveViewIdAndFolderPath, findAutoResolveConfig, } from "./client/auto-resolve.js";
 import { QMETRY_HANDLER_MAP } from "./client/handlers.js";
 import { getProjectInfo } from "./client/project.js";
 import { TOOLS } from "./client/tools/index.js";
 import { QMETRY_DEFAULTS } from "./config/constants.js";
+const ConfigurationSchema = z.object({
+    api_key: z.string().describe("QMetry API key for authentication"),
+    base_url: z
+        .string()
+        .url()
+        .optional()
+        .describe("Optional QMetry base URL for custom or region-specific endpoints"),
+});
 export class QmetryClient {
     name = "QMetry";
-    prefix = "qmetry";
+    toolPrefix = "qmetry";
+    configPrefix = "Qmetry";
+    config = ConfigurationSchema;
     token;
-    projectApiKey;
-    endpoint;
-    constructor(token, endpoint) {
-        this.token = token;
-        this.projectApiKey = QMETRY_DEFAULTS.PROJECT_KEY;
-        this.endpoint = endpoint || QMETRY_DEFAULTS.BASE_URL;
+    projectApiKey = QMETRY_DEFAULTS.PROJECT_KEY;
+    endpoint = QMETRY_DEFAULTS.BASE_URL;
+    async configure(_server, config, _cache) {
+        this.token = config.api_key;
+        if (config.base_url) {
+            this.endpoint = config.base_url;
+        }
+        return true;
     }
     getToken() {
+        if (!this.token)
+            throw new Error("Client not configured");
         return this.token;
     }
     getBaseUrl() {
@@ -70,7 +85,7 @@ export class QmetryClient {
                         needsParentFolderIdAutoResolve) {
                         let projectInfo;
                         try {
-                            projectInfo = (await getProjectInfo(this.token, baseUrl, projectKey));
+                            projectInfo = (await getProjectInfo(this.getToken(), baseUrl, projectKey));
                         }
                         catch (err) {
                             throw new Error(`Failed to auto-resolve viewId/folderPath/folderID for ${autoResolveConfig.moduleName} in project ${projectKey}. ` +
@@ -83,7 +98,7 @@ export class QmetryClient {
                 }
                 // Extract projectKey and baseUrl from arguments to prevent them from being sent in request body
                 const { projectKey: _, baseUrl: __, ...cleanArgs } = a;
-                const result = await handlerFn(this.token, baseUrl, projectKey, cleanArgs);
+                const result = await handlerFn(this.getToken(), baseUrl, projectKey, cleanArgs);
                 // Use custom formatter if available, otherwise return JSON
                 const formatted = tool.formatResponse
                     ? tool.formatResponse(result)