@centrali-io/centrali-mcp 4.4.5 → 4.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-mcp",
-  "version": "4.4.5",
+  "version": "4.4.7",
   "description": "Centrali MCP Server - AI assistant integration for Centrali workspaces",
   "main": "dist/index.js",
   "type": "commonjs",
@@ -25,7 +25,7 @@
   "author": "Blueinit",
   "license": "ISC",
   "dependencies": {
-    "@centrali-io/centrali-sdk": "^4.2.4",
+    "@centrali-io/centrali-sdk": "^4.4.7",
     "@modelcontextprotocol/sdk": "^1.12.1"
   },
   "devDependencies": {

package/src/index.ts

@@ -13,6 +13,8 @@ import { registerInsightTools } from "./tools/insights.js";
 import { registerValidationTools } from "./tools/validation.js";
 import { registerPageTools } from "./tools/pages.js";
 import { registerDescribeTools } from "./tools/describe.js";
+import { registerAuthProviderTools } from "./tools/auth-providers.js";
+import { registerServiceAccountTools } from "./tools/service-accounts.js";
 import { registerStructureResources, registerCollectionResources } from "./resources/structures.js";
 
 function getRequiredEnv(name: string): string {
@@ -47,12 +49,14 @@ async function main() {
   registerStructureTools(server, sdk);
   registerRecordTools(server, sdk);
   registerSearchTools(server, sdk);
-  registerComputeTools(server, sdk);
+  registerComputeTools(server, sdk, baseUrl, workspaceId);
   registerSmartQueryTools(server, sdk);
   registerOrchestrationTools(server, sdk);
   registerInsightTools(server, sdk);
   registerValidationTools(server, sdk);
   registerPageTools(server, sdk, baseUrl, workspaceId);
+  registerAuthProviderTools(server, sdk, baseUrl, workspaceId);
+  registerServiceAccountTools(server, sdk, baseUrl, workspaceId, clientId);
   registerDescribeTools(server);
 
   // Register resources

package/src/tools/auth-providers.ts

@@ -0,0 +1,290 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CentraliSDK } from "@centrali-io/centrali-sdk";
+import axios, { AxiosInstance } from "axios";
+import { z } from "zod";
+
+/**
+ * Ensures the SDK has a valid token by making a lightweight SDK call if needed.
+ */
+async function ensureToken(sdk: CentraliSDK): Promise<string | null> {
+  let token = sdk.getToken();
+  if (token) return token;
+  try {
+    await sdk.functions.list({ limit: 1 });
+  } catch {
+    // Ignore — we only need the token refresh side effect
+  }
+  return sdk.getToken();
+}
+
+/**
+ * Creates an axios instance for the IAM external auth provider API.
+ */
+function createIamClient(sdk: CentraliSDK, centraliUrl: string, workspaceId: string): AxiosInstance {
+  const url = new URL(centraliUrl);
+  const hostname = url.hostname.startsWith("auth.")
+    ? url.hostname
+    : `auth.${url.hostname.replace(/^api\./, '')}`;
+  const baseURL = `${url.protocol}//${hostname}/workspace/${workspaceId}/api/v1/external-auth-providers`;
+
+  const client = axios.create({ baseURL });
+
+  client.interceptors.request.use(async (config) => {
+    const token = await ensureToken(sdk);
+    if (token) {
+      config.headers.Authorization = `Bearer ${token}`;
+    }
+    return config;
+  });
+
+  client.interceptors.response.use(
+    (response) => response,
+    async (error) => {
+      const originalRequest = error.config;
+      const isAuthError = error.response?.status === 401 || error.response?.status === 403;
+
+      if (isAuthError && !originalRequest._hasRetried) {
+        originalRequest._hasRetried = true;
+        try {
+          await sdk.functions.list({ limit: 1 });
+        } catch { /* token refresh side effect */ }
+
+        const token = sdk.getToken();
+        if (token) {
+          originalRequest.headers.Authorization = `Bearer ${token}`;
+          return client.request(originalRequest);
+        }
+      }
+      return Promise.reject(error);
+    }
+  );
+
+  return client;
+}
+
+function formatError(error: unknown, context: string): string {
+  if (error && typeof error === "object") {
+    const e = error as Record<string, any>;
+    if (e.response?.data) {
+      const d = e.response.data;
+      const code = d.code ?? d.error?.code ?? e.response.status ?? "ERROR";
+      const message = d.message ?? d.error?.message ?? JSON.stringify(d);
+      return `Error ${context}: [${code}] ${message}`;
+    }
+    if ("message" in e) {
+      return `Error ${context}: ${e.message}`;
+    }
+  }
+  return `Error ${context}: ${error instanceof Error ? error.message : String(error)}`;
+}
+
+const ClaimMappingZod = z.object({
+  attribute: z.string().describe("Attribute name used in policies (automatically prefixed with ext_). Must start with a letter, alphanumeric + underscores only. Example: 'role' becomes ext_role in policies."),
+  jwtPath: z.string().describe("Dot-notation path to extract from the JWT payload. Examples: 'org_role', 'metadata.plan', 'organization.role'"),
+  required: z.boolean().optional().describe("If true, token validation fails when this claim is missing (default: false)"),
+  defaultValue: z.union([z.string(), z.number(), z.boolean(), z.array(z.string())]).optional().describe("Fallback value when claim is not present in the JWT"),
+  transform: z.enum(["lowercase", "uppercase", "string", "boolean", "array"]).optional().describe("Transform applied to the extracted value before use in policies"),
+});
+
+export function registerAuthProviderTools(server: McpServer, sdk: CentraliSDK, centraliUrl: string, workspaceId: string) {
+  const getClient = () => createIamClient(sdk, centraliUrl, workspaceId);
+
+  // ── List ──────────────────────────────────────────────────────────
+
+  server.tool(
+    "list_auth_providers",
+    "List external auth providers configured in the workspace. These are identity providers (Clerk, Auth0, Okta, etc.) that can issue JWTs accepted by Centrali for BYOT (Bring Your Own Token) authorization.",
+    {
+      includeInactive: z.boolean().optional().describe("Include inactive providers (default: false)"),
+    },
+    async ({ includeInactive }) => {
+      try {
+        const params: Record<string, any> = {};
+        if (includeInactive) params.includeInactive = true;
+        const result = await getClient().get("/", { params });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, "listing auth providers") }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Get ───────────────────────────────────────────────────────────
+
+  server.tool(
+    "get_auth_provider",
+    "Get details of an external auth provider by ID, including claim mappings and JWKS configuration.",
+    {
+      providerId: z.string().describe("The provider ID (UUID)"),
+    },
+    async ({ providerId }) => {
+      try {
+        const result = await getClient().get(`/${providerId}`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `getting auth provider '${providerId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Create ────────────────────────────────────────────────────────
+
+  server.tool(
+    "create_auth_provider",
+    "Create an external auth provider for BYOT (Bring Your Own Token). This lets your app's users authenticate with Clerk, Auth0, Okta, or any OIDC provider, and Centrali validates their JWTs and extracts claims for authorization policies. Call describe_auth_providers for the full setup guide.",
+    {
+      name: z.string().describe("Display name (e.g., 'Production Clerk')"),
+      slug: z.string().describe("URL-safe unique slug (lowercase, hyphens allowed, e.g., 'production-clerk')"),
+      providerType: z.enum(["oidc", "clerk", "auth0", "keycloak", "okta", "custom"]).describe("Identity provider type. Use 'clerk', 'auth0', 'okta', or 'keycloak' for built-in support, 'oidc' for any OIDC-compliant provider, or 'custom' for a custom JWT issuer."),
+      issuer: z.string().describe("The JWT issuer URL. Centrali auto-discovers JWKS from this. Examples: 'https://clerk.your-domain.com' for Clerk, 'https://your-tenant.auth0.com/' for Auth0, 'https://your-org.okta.com' for Okta."),
+      jwksUrl: z.string().optional().describe("Override JWKS URL if auto-discovery doesn't work (usually not needed for standard providers)"),
+      allowedAudiences: z.array(z.string()).optional().describe("JWT audience values to accept. If set, tokens without a matching 'aud' claim are rejected."),
+      clockSkewSeconds: z.number().optional().describe("Seconds of clock skew tolerance for token expiration (default: 60, max: 300)"),
+      allowedAlgorithms: z.array(z.enum(["RS256", "RS384", "RS512", "ES256", "ES384", "ES512"])).optional().describe("Accepted JWT signing algorithms (default: ['RS256'])"),
+      claimMappings: z.array(ClaimMappingZod).optional().describe("Map JWT claims to policy attributes. Each mapping extracts a value from the JWT and makes it available as ext_<attribute> in authorization policies. Example: { attribute: 'role', jwtPath: 'org_role' } makes ext_role available."),
+      allowedOrigins: z.array(z.string()).optional().describe("CORS origins allowed for browser requests with this provider's tokens"),
+    },
+    async ({ name, slug, providerType, issuer, jwksUrl, allowedAudiences, clockSkewSeconds, allowedAlgorithms, claimMappings, allowedOrigins }) => {
+      try {
+        const input: Record<string, any> = { name, slug, providerType, issuer };
+        if (jwksUrl !== undefined) input.jwksUrl = jwksUrl;
+        if (allowedAudiences !== undefined) input.allowedAudiences = allowedAudiences;
+        if (clockSkewSeconds !== undefined) input.clockSkewSeconds = clockSkewSeconds;
+        if (allowedAlgorithms !== undefined) input.allowedAlgorithms = allowedAlgorithms;
+        if (claimMappings !== undefined) input.claimMappings = claimMappings;
+        if (allowedOrigins !== undefined) input.allowedOrigins = allowedOrigins;
+
+        const result = await getClient().post("/", input);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `creating auth provider '${name}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Update ────────────────────────────────────────────────────────
+
+  server.tool(
+    "update_auth_provider",
+    "Update an external auth provider. Only include the fields you want to change. Use this to update claim mappings, allowed audiences, or deactivate a provider.",
+    {
+      providerId: z.string().describe("The provider ID (UUID) to update"),
+      name: z.string().optional().describe("Updated display name"),
+      jwksUrl: z.string().optional().describe("Updated JWKS URL"),
+      allowedAudiences: z.array(z.string()).optional().describe("Updated allowed audiences"),
+      clockSkewSeconds: z.number().optional().describe("Updated clock skew tolerance (0-300 seconds)"),
+      allowedAlgorithms: z.array(z.enum(["RS256", "RS384", "RS512", "ES256", "ES384", "ES512"])).optional().describe("Updated allowed algorithms"),
+      claimMappings: z.array(ClaimMappingZod).optional().describe("Updated claim mappings (replaces all existing mappings)"),
+      allowedOrigins: z.array(z.string()).optional().describe("Updated CORS origins"),
+      isActive: z.boolean().optional().describe("Set to false to deactivate the provider (tokens will be rejected)"),
+    },
+    async ({ providerId, name, jwksUrl, allowedAudiences, clockSkewSeconds, allowedAlgorithms, claimMappings, allowedOrigins, isActive }) => {
+      try {
+        const input: Record<string, any> = {};
+        if (name !== undefined) input.name = name;
+        if (jwksUrl !== undefined) input.jwksUrl = jwksUrl;
+        if (allowedAudiences !== undefined) input.allowedAudiences = allowedAudiences;
+        if (clockSkewSeconds !== undefined) input.clockSkewSeconds = clockSkewSeconds;
+        if (allowedAlgorithms !== undefined) input.allowedAlgorithms = allowedAlgorithms;
+        if (claimMappings !== undefined) input.claimMappings = claimMappings;
+        if (allowedOrigins !== undefined) input.allowedOrigins = allowedOrigins;
+        if (isActive !== undefined) input.isActive = isActive;
+
+        const result = await getClient().put(`/${providerId}`, input);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `updating auth provider '${providerId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Delete ────────────────────────────────────────────────────────
+
+  server.tool(
+    "delete_auth_provider",
+    "Delete an external auth provider. Tokens from this provider will no longer be accepted.",
+    {
+      providerId: z.string().describe("The provider ID (UUID) to delete"),
+    },
+    async ({ providerId }) => {
+      try {
+        await getClient().delete(`/${providerId}`);
+        return {
+          content: [{ type: "text", text: `Auth provider '${providerId}' deleted successfully.` }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `deleting auth provider '${providerId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Test Claim Extraction ─────────────────────────────────────────
+
+  server.tool(
+    "test_auth_provider",
+    "Test claim extraction for an auth provider by passing a sample JWT. Decodes the token (without signature verification) and shows which claims would be extracted using the provider's configured mappings. Use this to validate your claim mappings before deploying.",
+    {
+      providerId: z.string().describe("The provider ID (UUID) to test against"),
+      token: z.string().describe("A sample JWT token from your identity provider"),
+    },
+    async ({ providerId, token }) => {
+      try {
+        const result = await getClient().post(`/${providerId}/test-extraction`, { token });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `testing auth provider '${providerId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Refresh JWKS ──────────────────────────────────────────────────
+
+  server.tool(
+    "refresh_auth_provider_jwks",
+    "Force refresh the cached JWKS (JSON Web Key Set) for an auth provider. Use this after your identity provider rotates its signing keys.",
+    {
+      providerId: z.string().describe("The provider ID (UUID)"),
+    },
+    async ({ providerId }) => {
+      try {
+        const result = await getClient().post(`/${providerId}/refresh-jwks`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `refreshing JWKS for auth provider '${providerId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/compute.ts

@@ -1,5 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CentraliSDK } from "@centrali-io/centrali-sdk";
+import axios from "axios";
 import { z } from "zod";
 
 function formatError(error: unknown, context: string): string {
@@ -23,7 +24,19 @@ function formatError(error: unknown, context: string): string {
   return `Error ${context}: ${error instanceof Error ? error.message : String(error)}`;
 }
 
-export function registerComputeTools(server: McpServer, sdk: CentraliSDK) {
+/**
+ * Ensures the SDK has a valid token.
+ */
+async function ensureToken(sdk: CentraliSDK): Promise<string | null> {
+  let token = sdk.getToken();
+  if (token) return token;
+  try {
+    await sdk.functions.list({ limit: 1 });
+  } catch { /* token refresh side effect */ }
+  return sdk.getToken();
+}
+
+export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centraliUrl: string, workspaceId: string) {
   server.tool(
     "list_functions",
     "List all compute functions in the workspace. Compute functions are JavaScript code blocks that run server-side.",
@@ -61,10 +74,10 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK) {
 
   server.tool(
     "list_triggers",
-    "List function triggers in the workspace. Triggers define how and when compute functions are executed (on-demand, event-driven, scheduled, http-trigger).",
+    "List function triggers in the workspace. Triggers define how and when compute functions are executed (on-demand, event-driven, scheduled, http-trigger, endpoint).",
     {
       executionType: z
-        .enum(["on-demand", "event-driven", "scheduled", "http-trigger"])
+        .enum(["on-demand", "event-driven", "scheduled", "http-trigger", "endpoint"])
         .optional()
         .describe("Filter by trigger execution type"),
       page: z.number().optional().describe("Page number"),
@@ -118,7 +131,11 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK) {
             {
               type: "text",
               text: JSON.stringify(
-                { jobId: result.data, message: "Trigger invoked successfully" },
+                {
+                  jobId: result.data,
+                  message: "Trigger invoked successfully. Execution is async — the function is running in the background.",
+                  next_step: `To check the result, call get_compute_job_status with jobId='${result.data}'. It returns the job state (queued → running → completed | failed) and the return value or error.`,
+                },
                 null,
                 2
               ),
@@ -139,6 +156,43 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
+  server.tool(
+    "get_compute_job_status",
+    "Check the status of an async compute job by job ID. Returns the current state (queued, running, completed, failed), the return value on success, or the failure reason on error. Use this after invoke_trigger to poll for results.",
+    {
+      jobId: z.string().describe("The job ID returned by invoke_trigger"),
+    },
+    async ({ jobId }) => {
+      try {
+        const token = await ensureToken(sdk);
+        const url = new URL(centraliUrl);
+        const hostname = url.hostname.startsWith("api.")
+          ? url.hostname
+          : `api.${url.hostname}`;
+        const apiUrl = `${url.protocol}//${hostname}/data/workspace/${workspaceId}/api/v1/jobs/compute/${jobId}`;
+
+        const result = await axios.get(apiUrl, {
+          headers: token ? { Authorization: `Bearer ${token}` } : {},
+        });
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+          ],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatError(error, `getting job status for '${jobId}'`),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
   // ── Function CRUD tools ──────────────────────────────────────────
 
   server.tool(
@@ -383,13 +437,13 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK) {
       name: z.string().describe("Display name for the trigger"),
       functionId: z.string().describe("The compute function ID (UUID) to execute"),
       executionType: z
-        .enum(["on-demand", "event-driven", "scheduled", "http-trigger"])
-        .describe("How the trigger fires: on-demand (manual), event-driven (data events), scheduled (cron), or http-trigger (external HTTP POST)"),
+        .enum(["on-demand", "event-driven", "scheduled", "http-trigger", "endpoint"])
+        .describe("How the trigger fires: on-demand (manual), event-driven (data events), scheduled (cron), http-trigger (external HTTP POST), or endpoint (synchronous HTTP API — returns response inline)"),
       description: z.string().optional().describe("Optional description"),
       triggerMetadata: z
         .record(z.string(), z.any())
         .optional()
-        .describe("Type-specific configuration. For event-driven: { eventType, recordSlug } where eventType is record_created | record_updated | record_deleted. For scheduled: { scheduleType, cronExpression, timezone }. For http-trigger: auto-generated URL."),
+        .describe("Type-specific configuration. For event-driven: { eventType, recordSlug }. For scheduled: { scheduleType, cronExpression, timezone }. For http-trigger: auto-generated URL. For endpoint: { path, allowedMethods?, timeoutMs?, auth? } where path is URL-safe (e.g., 'create-order'), allowedMethods defaults to ['POST'], timeoutMs 1000-30000 (default 30000), auth is { mode: 'bearer'|'public'|'apiKey'|'hmac' }."),
       enabled: z.boolean().optional().describe("Whether the trigger is enabled (default: true)"),
     },
     async ({ name, functionId, executionType, description, triggerMetadata, enabled }) => {
@@ -547,6 +601,147 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
+  // ── Function Runs tools ────────────────────────────────────────────
+
+  server.tool(
+    "get_function_run",
+    "Get a function run by ID. Returns status, output, error, timing, and execution metadata. Use this to check the result of an async trigger invocation or test execution.",
+    {
+      runId: z.string().describe("The function run ID (UUID)"),
+    },
+    async ({ runId }) => {
+      try {
+        const result = await sdk.runs.get(runId);
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+          ],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatError(error, `getting function run '${runId}'`),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "list_function_runs",
+    "List function runs filtered by trigger ID or function ID. Returns execution history with status, timing, and errors. Useful for checking whether a trigger invocation completed and what it returned.",
+    {
+      triggerId: z.string().optional().describe("Filter runs by trigger ID (UUID)"),
+      functionId: z.string().optional().describe("Filter runs by function ID (UUID)"),
+      status: z
+        .enum(["pending", "running", "completed", "failure", "timeout"])
+        .optional()
+        .describe("Filter by run status"),
+      page: z.number().optional().describe("Page number"),
+      limit: z.number().optional().describe("Results per page"),
+    },
+    async ({ triggerId, functionId, status, page, limit }) => {
+      try {
+        if (!triggerId && !functionId) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Error: provide either triggerId or functionId to list runs.",
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        const options: Record<string, any> = {};
+        if (status) options.status = status;
+        if (page !== undefined) options.page = page;
+        if (limit !== undefined) options.limit = limit;
+
+        const opts = Object.keys(options).length > 0 ? options : undefined;
+        const result = triggerId
+          ? await sdk.runs.listByTrigger(triggerId, opts)
+          : await sdk.runs.listByFunction(functionId!, opts);
+
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+          ],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatError(error, `listing function runs`),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Endpoint Trigger (Sync Execution) ─────────────────────────────
+
+  server.tool(
+    "invoke_endpoint",
+    "Invoke a compute endpoint trigger by path. The function executes synchronously — Centrali waits for the function to complete and returns its output directly in the response. No polling needed. Max execution time: 30 seconds (configurable via triggerMetadata.timeoutMs, range 1–30s). If the function exceeds the timeout, returns 504. Endpoint triggers must be created first with executionType='endpoint'. Use this for real-time API responses; use invoke_trigger for long-running background work that doesn't need an immediate response.",
+    {
+      path: z.string().describe("The endpoint path (e.g., 'create-order', 'webhook/shipments'). This is set in the trigger's triggerMetadata.path."),
+      method: z.enum(["GET", "POST", "PUT", "DELETE", "PATCH"]).optional().describe("HTTP method (default: POST). Must be in the trigger's allowedMethods."),
+      payload: z.record(z.string(), z.any()).optional().describe("Request body payload (sent as JSON)"),
+      headers: z.record(z.string(), z.string()).optional().describe("Additional headers (e.g., X-API-Key for apiKey auth)"),
+    },
+    async ({ path, method, payload, headers: extraHeaders }) => {
+      try {
+        const token = await ensureToken(sdk);
+        const url = new URL(centraliUrl);
+        const hostname = url.hostname.startsWith("api.")
+          ? url.hostname
+          : `api.${url.hostname}`;
+        const apiUrl = `${url.protocol}//${hostname}/data/workspace/${workspaceId}/api/v1/endpoints/${path}`;
+
+        const reqHeaders: Record<string, string> = {};
+        if (token) reqHeaders.Authorization = `Bearer ${token}`;
+        if (extraHeaders) Object.assign(reqHeaders, extraHeaders);
+
+        const httpMethod = (method || "POST").toLowerCase();
+        const result = await axios({
+          method: httpMethod as any,
+          url: apiUrl,
+          data: ["get", "delete"].includes(httpMethod) ? undefined : (payload || {}),
+          headers: reqHeaders,
+          validateStatus: () => true, // Don't throw on non-2xx — return the function's response as-is
+        });
+
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              status: result.status,
+              headers: {
+                "content-type": result.headers["content-type"],
+                "x-execution-id": result.headers["x-execution-id"],
+              },
+              body: result.data,
+            }, null, 2),
+          }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `invoking endpoint '${path}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
   // ── Allowed Domains tools ──────────────────────────────────────────
 
   server.tool(