@ateam-ai/mcp 0.1.2 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ateam-ai/mcp",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "mcpName": "io.github.ariekogan/ateam-mcp",
   "description": "ADAS MCP Server — build, validate, and deploy multi-agent solutions from any AI environment",
   "type": "module",

package/src/api.js

@@ -1,50 +1,179 @@
 /**
  * ADAS API client — thin HTTP wrapper for the External Agent API.
+ *
+ * Credentials resolve in this order:
+ *   1. Per-session override (set via adas_auth tool — used by HTTP transport)
+ *   2. Environment variables (ADAS_API_KEY, ADAS_TENANT — used by stdio transport)
+ *   3. Defaults (no key, tenant "main")
  */
 
 const BASE_URL = process.env.ADAS_API_URL || "https://api.ateam-ai.com";
-const TENANT = process.env.ADAS_TENANT || "main";
-const API_KEY = process.env.ADAS_API_KEY || "";
-
-function headers() {
-  return {
-    "Content-Type": "application/json",
-    "X-ADAS-TENANT": TENANT,
-    "X-API-KEY": API_KEY,
+const ENV_TENANT = process.env.ADAS_TENANT || "";
+const ENV_API_KEY = process.env.ADAS_API_KEY || "";
+
+// Request timeout (30 seconds)
+const REQUEST_TIMEOUT_MS = 30_000;
+
+// Per-session credential store (sessionId → { tenant, apiKey })
+const sessions = new Map();
+
+/**
+ * Parse a tenant-embedded API key.
+ * Format: adas_<tenant>_<32hex>
+ * Legacy: adas_<32hex> (no tenant embedded)
+ * @returns {{ tenant: string|null, isValid: boolean }}
+ */
+export function parseApiKey(key) {
+  if (!key || typeof key !== 'string') return { tenant: null, isValid: false };
+  const match = key.match(/^adas_([a-z0-9][a-z0-9-]{0,28}[a-z0-9])_([0-9a-f]{32})$/);
+  if (match) return { tenant: match[1], isValid: true };
+  const legacy = key.match(/^adas_([0-9a-f]{32})$/);
+  if (legacy) return { tenant: null, isValid: true };
+  return { tenant: null, isValid: false };
+}
+
+/**
+ * Set credentials for a session (called by adas_auth tool).
+ * If tenant is not provided, it's auto-extracted from the key.
+ */
+export function setSessionCredentials(sessionId, { tenant, apiKey }) {
+  let resolvedTenant = tenant;
+  if (!resolvedTenant && apiKey) {
+    const parsed = parseApiKey(apiKey);
+    if (parsed.tenant) resolvedTenant = parsed.tenant;
+  }
+  sessions.set(sessionId, { tenant: resolvedTenant || "main", apiKey });
+}
+
+/**
+ * Get credentials for a session, falling back to env vars.
+ * If using env var key with embedded tenant and no explicit ADAS_TENANT, auto-extract.
+ */
+export function getCredentials(sessionId) {
+  const session = sessionId ? sessions.get(sessionId) : null;
+  if (session) {
+    return { tenant: session.tenant, apiKey: session.apiKey };
+  }
+  const apiKey = ENV_API_KEY || "";
+  let tenant = ENV_TENANT;
+  if (!tenant && apiKey) {
+    const parsed = parseApiKey(apiKey);
+    if (parsed.tenant) tenant = parsed.tenant;
+  }
+  return { tenant: tenant || "main", apiKey };
+}
+
+/**
+ * Check if a session is authenticated (has an API key from any source).
+ */
+export function isAuthenticated(sessionId) {
+  const { apiKey } = getCredentials(sessionId);
+  return apiKey.length > 0;
+}
+
+/**
+ * Remove session credentials (on disconnect).
+ */
+export function clearSession(sessionId) {
+  sessions.delete(sessionId);
+}
+
+function headers(sessionId) {
+  const { tenant, apiKey } = getCredentials(sessionId);
+  const h = { "Content-Type": "application/json" };
+  if (tenant) h["X-ADAS-TENANT"] = tenant;
+  if (apiKey) h["X-API-KEY"] = apiKey;
+  return h;
+}
+
+/**
+ * Format an API error into a user-friendly message with actionable hints.
+ */
+function formatError(method, path, status, body) {
+  const hints = {
+    401: "Your API key may be invalid or expired. Try calling adas_auth again with a valid key.",
+    403: "You don't have permission for this operation. Check your tenant and API key.",
+    404: "Resource not found. Check the solution_id or skill_id you're using. Use adas_list_solutions to see available solutions.",
+    409: "Conflict — the resource may already exist or is in a conflicting state.",
+    422: "Validation failed. Check the request payload against the spec (use adas_get_spec).",
+    429: "Rate limited. Wait a moment and try again.",
+    500: "ADAS server error. The platform may be temporarily unavailable. Try again in a minute.",
+    502: "ADAS API is unreachable. The service may be restarting. Try again in a minute.",
+    503: "ADAS API is temporarily unavailable. Try again in a minute.",
   };
+
+  const hint = hints[status] || "";
+  const detail = typeof body === "string" && body.length > 0 && body.length < 500 ? body : "";
+
+  let msg = `ADAS API error: ${method} ${path} returned ${status}`;
+  if (detail) msg += ` — ${detail}`;
+  if (hint) msg += `\nHint: ${hint}`;
+
+  return msg;
+}
+
+/**
+ * Core fetch wrapper with timeout and error formatting.
+ */
+async function request(method, path, body, sessionId) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+
+  try {
+    const opts = {
+      method,
+      headers: headers(sessionId),
+      signal: controller.signal,
+    };
+    if (body !== undefined) {
+      opts.body = JSON.stringify(body);
+    }
+
+    const res = await fetch(`${BASE_URL}${path}`, opts);
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(formatError(method, path, res.status, text));
+    }
+
+    return res.json();
+  } catch (err) {
+    if (err.name === "AbortError") {
+      throw new Error(
+        `ADAS API timeout: ${method} ${path} did not respond within ${REQUEST_TIMEOUT_MS / 1000}s.\n` +
+        `Hint: The ADAS API at ${BASE_URL} may be down. Check https://api.ateam-ai.com/health`
+      );
+    }
+    if (err.cause?.code === "ECONNREFUSED") {
+      throw new Error(
+        `Cannot connect to ADAS API at ${BASE_URL}.\n` +
+        `Hint: The service may be down. Check https://api.ateam-ai.com/health`
+      );
+    }
+    if (err.cause?.code === "ENOTFOUND") {
+      throw new Error(
+        `Cannot resolve ADAS API host: ${BASE_URL}.\n` +
+        `Hint: Check your internet connection and ADAS_API_URL setting.`
+      );
+    }
+    throw err;
+  } finally {
+    clearTimeout(timeout);
+  }
 }
 
-export async function get(path) {
-  const res = await fetch(`${BASE_URL}${path}`, { headers: headers() });
-  if (!res.ok) throw new Error(`GET ${path} → ${res.status}: ${await res.text()}`);
-  return res.json();
+export async function get(path, sessionId) {
+  return request("GET", path, undefined, sessionId);
 }
 
-export async function post(path, body) {
-  const res = await fetch(`${BASE_URL}${path}`, {
-    method: "POST",
-    headers: headers(),
-    body: JSON.stringify(body),
-  });
-  if (!res.ok) throw new Error(`POST ${path} → ${res.status}: ${await res.text()}`);
-  return res.json();
+export async function post(path, body, sessionId) {
+  return request("POST", path, body, sessionId);
 }
 
-export async function patch(path, body) {
-  const res = await fetch(`${BASE_URL}${path}`, {
-    method: "PATCH",
-    headers: headers(),
-    body: JSON.stringify(body),
-  });
-  if (!res.ok) throw new Error(`PATCH ${path} → ${res.status}: ${await res.text()}`);
-  return res.json();
+export async function patch(path, body, sessionId) {
+  return request("PATCH", path, body, sessionId);
 }
 
-export async function del(path) {
-  const res = await fetch(`${BASE_URL}${path}`, {
-    method: "DELETE",
-    headers: headers(),
-  });
-  if (!res.ok) throw new Error(`DELETE ${path} → ${res.status}: ${await res.text()}`);
-  return res.json();
+export async function del(path, sessionId) {
+  return request("DELETE", path, undefined, sessionId);
 }

package/src/http.js

@@ -8,6 +8,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import express from "express";
 import { createServer } from "./server.js";
+import { clearSession } from "./api.js";
 
 // Active sessions
 const transports = {};
@@ -21,6 +22,11 @@ export function startHttpServer(port = 3100) {
     res.json({ ok: true, service: "ateam-mcp", transport: "http" });
   });
 
+  // ─── Get API Key — redirect to Skill Builder with auto-open ──
+  app.get("/get-api-key", (_req, res) => {
+    res.redirect("https://app.ateam-ai.com/builder/?show=api-key");
+  });
+
   // ─── MCP POST — handle tool calls + initialize ───────────────
   app.post("/mcp", async (req, res) => {
     const sessionId = req.headers["mcp-session-id"];
@@ -32,9 +38,11 @@ export function startHttpServer(port = 3100) {
         // Reuse existing session
         transport = transports[sessionId];
       } else if (!sessionId && isInitializeRequest(req.body)) {
-        // New session
+        // New session — generate ID upfront so we can bind it to the server
+        const newSessionId = randomUUID();
+
         transport = new StreamableHTTPServerTransport({
-          sessionIdGenerator: () => randomUUID(),
+          sessionIdGenerator: () => newSessionId,
           onsessioninitialized: (sid) => {
             transports[sid] = transport;
           },
@@ -42,12 +50,13 @@ export function startHttpServer(port = 3100) {
 
         transport.onclose = () => {
           const sid = transport.sessionId;
-          if (sid && transports[sid]) {
+          if (sid) {
             delete transports[sid];
+            clearSession(sid); // drop per-session credentials
           }
         };
 
-        const server = createServer();
+        const server = createServer(newSessionId);
         await server.connect(transport);
         await transport.handleRequest(req, res, req.body);
         return;
@@ -107,6 +116,7 @@ export function startHttpServer(port = 3100) {
         await transports[sid].close();
       } catch {}
       delete transports[sid];
+      clearSession(sid);
     }
     process.exit(0);
   });

package/src/server.js

@@ -1,5 +1,8 @@
 /**
  * Shared MCP server factory — used by both stdio and HTTP transports.
+ *
+ * Each server instance is bound to a sessionId so that tool handlers
+ * can resolve per-session credentials (set via the adas_auth tool).
  */
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -9,9 +12,13 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import { tools, handleToolCall } from "./tools.js";
 
-export function createServer() {
+/**
+ * @param {string} sessionId — identifier for credential isolation.
+ *   HTTP transport passes the MCP session UUID; stdio uses "stdio".
+ */
+export function createServer(sessionId = "stdio") {
   const server = new Server(
-    { name: "ateam-mcp", version: "0.1.0" },
+    { name: "ateam-mcp", version: "0.1.5" },
     { capabilities: { tools: {} } }
   );
 
@@ -19,7 +26,7 @@ export function createServer() {
 
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
-    return handleToolCall(name, args);
+    return handleToolCall(name, args, sessionId);
   });
 
   return server;

package/src/tools.js

@@ -1,17 +1,48 @@
 /**
  * ADAS MCP tool definitions and handlers.
- * 12 tools covering the full ADAS External Agent API.
+ * 15 tools covering the full ADAS External Agent API + auth + bootstrap.
  */
 
-import { get, post, patch, del } from "./api.js";
+import {
+  get, post, patch, del,
+  setSessionCredentials, isAuthenticated, getCredentials, parseApiKey,
+} from "./api.js";
 
 // ─── Tool definitions ───────────────────────────────────────────────
 
 export const tools = [
+  {
+    name: "adas_bootstrap",
+    description:
+      "Call this FIRST after installing A-Team MCP. Returns a structured overview of what A-Team is, what the user can build, and the recommended step-by-step flow. Includes the first questions to ask the user and suggested next tool calls.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+  {
+    name: "adas_auth",
+    description:
+      "Authenticate with ADAS. Required before deploying or modifying solutions. The user can get their API key at https://mcp.ateam-ai.com/get-api-key. Read-only operations (spec, examples, validate) work without auth.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        api_key: {
+          type: "string",
+          description: "Your ADAS API key (e.g., adas_xxxxx)",
+        },
+        tenant: {
+          type: "string",
+          description: "Tenant name (e.g., dev, main). Optional if your key has the format adas_<tenant>_<hex> — the tenant is auto-extracted.",
+        },
+      },
+      required: ["api_key"],
+    },
+  },
   {
     name: "adas_get_spec",
     description:
-      "Get the ADAS specification — schemas, validation rules, system tools, agent guides, and templates. Use this to understand how to build skills and solutions.",
+      "Get the ADAS specification — schemas, validation rules, system tools, agent guides, and templates. Start here after bootstrap to understand how to build skills and solutions.",
     inputSchema: {
       type: "object",
       properties: {
@@ -25,6 +56,15 @@ export const tools = [
       required: ["topic"],
     },
   },
+  {
+    name: "adas_get_workflows",
+    description:
+      "Get the builder workflows — step-by-step state machines for building skills and solutions. Use this to guide users through the entire build process conversationally. Returns phases, what to ask, what to build, exit criteria, and tips for each stage.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
   {
     name: "adas_get_examples",
     description:
@@ -45,7 +85,7 @@ export const tools = [
   {
     name: "adas_validate_skill",
     description:
-      "Validate a skill definition through the 5-stage ADAS validation pipeline. Returns errors and suggestions to fix.",
+      "Validate a skill definition through the 5-stage ADAS validation pipeline. Returns errors and suggestions to fix. Always validate before deploying.",
     inputSchema: {
       type: "object",
       properties: {
@@ -60,7 +100,7 @@ export const tools = [
   {
     name: "adas_validate_solution",
     description:
-      "Validate a solution definition — cross-skill contracts, grant economy, handoffs, and LLM quality scoring.",
+      "Validate a solution definition — cross-skill contracts, grant economy, handoffs, and LLM quality scoring. Always validate before deploying.",
     inputSchema: {
       type: "object",
       properties: {
@@ -80,7 +120,7 @@ export const tools = [
   {
     name: "adas_deploy_solution",
     description:
-      "Deploy a complete solution to ADAS Core — identity, connectors, skills. The Skill Builder auto-generates MCP servers from tool definitions. This is the main deployment action.",
+      "Deploy a complete solution to ADAS Core — identity, connectors, skills. The Skill Builder auto-generates MCP servers from tool definitions. This is the main deployment action. Always validate first using adas_validate_solution. Requires authentication (call adas_auth first if not using env vars).",
     inputSchema: {
       type: "object",
       properties: {
@@ -109,7 +149,7 @@ export const tools = [
   },
   {
     name: "adas_deploy_skill",
-    description: "Deploy a single skill into an existing solution.",
+    description: "Deploy a single skill into an existing solution. Requires authentication.",
     inputSchema: {
       type: "object",
       properties: {
@@ -127,7 +167,7 @@ export const tools = [
   },
   {
     name: "adas_deploy_connector",
-    description: "Deploy a connector — registers in the Skill Builder catalog and connects in ADAS Core.",
+    description: "Deploy a connector — registers in the Skill Builder catalog and connects in ADAS Core. Requires authentication.",
     inputSchema: {
       type: "object",
       properties: {
@@ -175,7 +215,7 @@ export const tools = [
   {
     name: "adas_update",
     description:
-      "Update a deployed solution or skill incrementally using PATCH. Supports dot notation for scalar fields and _push/_delete/_update for arrays.",
+      "Update a deployed solution or skill incrementally using PATCH. Supports dot notation for scalar fields and _push/_delete/_update for arrays. Requires authentication.",
     inputSchema: {
       type: "object",
       properties: {
@@ -204,7 +244,7 @@ export const tools = [
   {
     name: "adas_redeploy",
     description:
-      "Re-deploy after making updates. Regenerates MCP servers and pushes to ADAS Core.",
+      "Re-deploy after making updates. Regenerates MCP servers and pushes to ADAS Core. Requires authentication.",
     inputSchema: {
       type: "object",
       properties: {
@@ -258,30 +298,103 @@ const EXAMPLE_PATHS = {
   solution: "/spec/examples/solution",
 };
 
+// Tools that require authentication (write operations)
+const WRITE_TOOLS = new Set([
+  "adas_deploy_solution",
+  "adas_deploy_skill",
+  "adas_deploy_connector",
+  "adas_update",
+  "adas_redeploy",
+  "adas_solution_chat",
+]);
+
 const handlers = {
-  adas_get_spec: async ({ topic }) => get(SPEC_PATHS[topic]),
+  adas_bootstrap: async () => ({
+    product_name: "A-Team (ADAS)",
+    what_this_mcp_is:
+      "A-Team MCP is a collection of tools that lets an AI assistant generate, validate, deploy, and iterate multi-agent Teams on the A-Team/ADAS platform.",
+    core_concepts: [
+      { term: "Skill", meaning: "One agent: role, intents, tools, policies, workflows" },
+      { term: "Solution", meaning: "A Team: multiple skills + routing + grants + handoffs" },
+      { term: "Connector", meaning: "External system integration via MCP tools" },
+      { term: "Deploy", meaning: "Make the Team runnable on ADAS Core" },
+    ],
+    recommended_flow: [
+      { step: 1, title: "Clarify the goal", description: "Understand what the user wants their Team to do", suggested_tools: [] },
+      { step: 2, title: "Generate Team map", description: "Design skills, solution architecture, and connectors", suggested_tools: ["adas_get_spec", "adas_get_examples", "adas_get_workflows"] },
+      { step: 3, title: "Validate", description: "Run validation before deploying", suggested_tools: ["adas_validate_skill", "adas_validate_solution"] },
+      { step: 4, title: "Deploy", description: "Push the Team to ADAS Core", suggested_tools: ["adas_auth", "adas_deploy_solution"] },
+      { step: 5, title: "Iterate", description: "Inspect, update, and redeploy as needed", suggested_tools: ["adas_get_solution", "adas_update", "adas_redeploy", "adas_solution_chat"] },
+    ],
+    first_questions: [
+      { id: "goal", question: "What do you want your Team to accomplish?", type: "text" },
+      { id: "domain", question: "Which domain fits best?", type: "enum", options: ["ecommerce", "logistics", "enterprise_ops", "other"] },
+      { id: "systems", question: "Which systems should the Team connect to?", type: "multi_select", options: ["slack", "email", "zendesk", "shopify", "jira", "postgres", "custom_api", "none"] },
+      { id: "security", question: "What environment constraints?", type: "enum", options: ["sandbox", "controlled", "regulated"] },
+    ],
+    assistant_instructions: {
+      always: [
+        "Explain Skill vs Solution vs Connector before deploying anything",
+        "Validate before deploy",
+        "Ask discovery questions if goal unclear",
+      ],
+      never: [
+        "Deploy before validation",
+        "Dump raw spec unless requested",
+      ],
+    },
+  }),
 
-  adas_get_examples: async ({ type }) => get(EXAMPLE_PATHS[type]),
+  adas_auth: async ({ api_key, tenant }, sessionId) => {
+    // Auto-extract tenant from key if not provided
+    let resolvedTenant = tenant;
+    if (!resolvedTenant) {
+      const parsed = parseApiKey(api_key);
+      resolvedTenant = parsed.tenant || "main";
+    }
+    setSessionCredentials(sessionId, { tenant: resolvedTenant, apiKey: api_key });
+    // Verify the key works by listing solutions
+    try {
+      const result = await get("/deploy/solutions", sessionId);
+      return {
+        ok: true,
+        tenant: resolvedTenant,
+        message: `Authenticated to tenant "${resolvedTenant}". ${result.solutions?.length || 0} solution(s) found.`,
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        tenant: resolvedTenant,
+        message: `Authentication failed: ${err.message}. The user can get a valid API key at https://mcp.ateam-ai.com/get-api-key`,
+      };
+    }
+  },
+
+  adas_get_spec: async ({ topic }, sid) => get(SPEC_PATHS[topic], sid),
+
+  adas_get_workflows: async (_args, sid) => get("/spec/workflows", sid),
+
+  adas_get_examples: async ({ type }, sid) => get(EXAMPLE_PATHS[type], sid),
 
-  adas_validate_skill: async ({ skill }) => post("/validate/skill", { skill }),
+  adas_validate_skill: async ({ skill }, sid) => post("/validate/skill", { skill }, sid),
 
-  adas_validate_solution: async ({ solution, skills }) =>
-    post("/validate/solution", { solution, skills }),
+  adas_validate_solution: async ({ solution, skills }, sid) =>
+    post("/validate/solution", { solution, skills }, sid),
 
-  adas_deploy_solution: async ({ solution, skills, connectors, mcp_store }) =>
-    post("/deploy/solution", { solution, skills, connectors, mcp_store }),
+  adas_deploy_solution: async ({ solution, skills, connectors, mcp_store }, sid) =>
+    post("/deploy/solution", { solution, skills, connectors, mcp_store }, sid),
 
-  adas_deploy_skill: async ({ solution_id, skill }) =>
-    post(`/deploy/solutions/${solution_id}/skills`, { skill }),
+  adas_deploy_skill: async ({ solution_id, skill }, sid) =>
+    post(`/deploy/solutions/${solution_id}/skills`, { skill }, sid),
 
-  adas_deploy_connector: async ({ connector }) =>
-    post("/deploy/connector", { connector }),
+  adas_deploy_connector: async ({ connector }, sid) =>
+    post("/deploy/connector", { connector }, sid),
 
-  adas_list_solutions: async () => get("/deploy/solutions"),
+  adas_list_solutions: async (_args, sid) => get("/deploy/solutions", sid),
 
-  adas_get_solution: async ({ solution_id, view, skill_id }) => {
+  adas_get_solution: async ({ solution_id, view, skill_id }, sid) => {
     const base = `/deploy/solutions/${solution_id}`;
-    if (skill_id) return get(`${base}/skills/${skill_id}`);
+    if (skill_id) return get(`${base}/skills/${skill_id}`, sid);
     const paths = {
       definition: `${base}/definition`,
       skills: `${base}/skills`,
@@ -291,30 +404,88 @@ const handlers = {
       validate: `${base}/validate`,
       connectors_health: `${base}/connectors/health`,
     };
-    return get(paths[view]);
+    return get(paths[view], sid);
   },
 
-  adas_update: async ({ solution_id, target, skill_id, updates }) => {
+  adas_update: async ({ solution_id, target, skill_id, updates }, sid) => {
     if (target === "skill") {
-      return patch(`/deploy/solutions/${solution_id}/skills/${skill_id}`, { updates });
+      return patch(`/deploy/solutions/${solution_id}/skills/${skill_id}`, { updates }, sid);
     }
-    return patch(`/deploy/solutions/${solution_id}`, { state_update: updates });
+    return patch(`/deploy/solutions/${solution_id}`, { state_update: updates }, sid);
   },
 
-  adas_redeploy: async ({ solution_id, skill_id }) => {
+  adas_redeploy: async ({ solution_id, skill_id }, sid) => {
     if (skill_id) {
-      return post(`/deploy/solutions/${solution_id}/skills/${skill_id}/redeploy`, {});
+      return post(`/deploy/solutions/${solution_id}/skills/${skill_id}/redeploy`, {}, sid);
     }
-    return post(`/deploy/solutions/${solution_id}/redeploy`, {});
+    return post(`/deploy/solutions/${solution_id}/redeploy`, {}, sid);
   },
 
-  adas_solution_chat: async ({ solution_id, message }) =>
-    post(`/deploy/solutions/${solution_id}/chat`, { message }),
+  adas_solution_chat: async ({ solution_id, message }, sid) =>
+    post(`/deploy/solutions/${solution_id}/chat`, { message }, sid),
 };
 
+// ─── Response formatting ────────────────────────────────────────────
+
+// Max characters to send back in a single tool response.
+// Larger payloads get summarized to avoid overwhelming LLM context.
+const MAX_RESPONSE_CHARS = 50_000;
+
+/**
+ * Format tool results — summarize oversized payloads.
+ */
+function formatResult(result, toolName) {
+  const json = JSON.stringify(result, null, 2);
+
+  if (json.length <= MAX_RESPONSE_CHARS) {
+    return json;
+  }
+
+  // For large responses, provide a summary + truncated data
+  const summary = summarizeLargeResult(result, toolName);
+  return summary + `\n\n(Response truncated from ${json.length.toLocaleString()} chars. Use more specific queries to get smaller results.)`;
+}
+
+/**
+ * Create a useful summary for large results.
+ */
+function summarizeLargeResult(result, toolName) {
+  // Spec responses — keep content but cap size
+  if (toolName === "adas_get_spec" && result && typeof result === "object") {
+    const keys = Object.keys(result);
+    return JSON.stringify({
+      _note: `ADAS spec with ${keys.length} sections. Content truncated — ask about specific sections for detail.`,
+      sections: keys,
+      ...result,
+    }, null, 2).slice(0, MAX_RESPONSE_CHARS);
+  }
+
+  // Validation results — keep errors/warnings, trim echoed input
+  if ((toolName === "adas_validate_skill" || toolName === "adas_validate_solution") && result) {
+    const slim = { ...result };
+    if (slim.skill) delete slim.skill;
+    if (slim.solution) delete slim.solution;
+    const slimJson = JSON.stringify(slim, null, 2);
+    if (slimJson.length <= MAX_RESPONSE_CHARS) return slimJson;
+  }
+
+  // Export results — summarize structure
+  if (toolName === "adas_get_solution" && result?.skills) {
+    return JSON.stringify({
+      _note: `Solution with ${result.skills.length} skill(s). Use adas_get_solution with skill_id to inspect individual skills.`,
+      solution_id: result.solution?.id || result.id,
+      skill_ids: result.skills.map(s => s.id || s.name),
+      ...result,
+    }, null, 2).slice(0, MAX_RESPONSE_CHARS);
+  }
+
+  // Generic fallback — truncate
+  return JSON.stringify(result, null, 2).slice(0, MAX_RESPONSE_CHARS);
+}
+
 // ─── Dispatcher ─────────────────────────────────────────────────────
 
-export async function handleToolCall(name, args) {
+export async function handleToolCall(name, args, sessionId) {
   const handler = handlers[name];
   if (!handler) {
     return {
@@ -322,14 +493,36 @@ export async function handleToolCall(name, args) {
       isError: true,
     };
   }
+
+  // Check auth for write operations
+  if (WRITE_TOOLS.has(name) && !isAuthenticated(sessionId)) {
+    return {
+      content: [{
+        type: "text",
+        text: [
+          "🔐 Authentication required.",
+          "",
+          "This tool needs an API key. Please ask the user to:",
+          "",
+          "1. Get their API key at: https://mcp.ateam-ai.com/get-api-key",
+          "2. Then call: adas_auth(api_key: \"<their key>\")",
+          "",
+          "The key looks like: adas_<tenant>_<32hex>",
+          "The tenant is auto-extracted — no separate tenant parameter needed.",
+        ].join("\n"),
+      }],
+      isError: true,
+    };
+  }
+
   try {
-    const result = await handler(args);
+    const result = await handler(args, sessionId);
     return {
-      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      content: [{ type: "text", text: formatResult(result, name) }],
     };
   } catch (err) {
     return {
-      content: [{ type: "text", text: `Error: ${err.message}` }],
+      content: [{ type: "text", text: err.message }],
       isError: true,
     };
   }