@ateam-ai/mcp 0.1.3 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ateam-ai/mcp",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "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.6" },
     { 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.
- * 13 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 when A-Team MCP is connected. Returns platform positioning, product vision, example solutions, and assistant behavior instructions for onboarding.",
+    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: {
@@ -54,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. Part of building a governed AI Team solution. Returns errors and suggestions to fix. Always validate before deploying.",
     inputSchema: {
       type: "object",
       properties: {
@@ -69,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 governed AI Team solution — cross-skill contracts, grant economy, handoffs, and LLM quality scoring. Part of building a governed AI Team solution. Always validate before deploying.",
     inputSchema: {
       type: "object",
       properties: {
@@ -89,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 governed AI Team solution to ADAS Core — identity, connectors, skills. The Skill Builder auto-generates MCP servers from tool definitions. Used after defining system architecture. Always validate first using adas_validate_solution. Requires authentication (call adas_auth first if not using env vars).",
     inputSchema: {
       type: "object",
       properties: {
@@ -118,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: {
@@ -136,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: {
@@ -184,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: {
@@ -213,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: {
@@ -267,32 +298,129 @@ 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 () => ({
+    platform_positioning: {
+      name: "A-Team",
+      category: "AI Team Solution Platform",
+      summary: "A-Team is a platform for building governed AI Teams as complete operational solutions.",
+    },
+    what_is_a_team: {
+      definition: "A Team is a structured multi-role AI system composed of Skills, Connectors, Governance contracts, and Managed Runtime deployment.",
+      core_components: {
+        skill: "Operational AI role — intents, tools, policies, workflows",
+        solution: "Complete AI Team system — multiple skills + routing + grants + handoffs",
+        connector: "External system integration via MCP tools",
+        governance: "Permissions, grants, handoffs, auditability",
+        deploy: "Activation into controlled runtime on ADAS Core",
+      },
+    },
+    example_solutions: [
+      { name: "Fleet Command Center", description: "Live vehicle tracking, route optimization, safety monitoring, governed execution" },
+      { name: "Customer Support Operations Team", description: "Multi-role support system with escalation, refund controls, CRM integration" },
+      { name: "Enterprise Compliance Platform", description: "Approval flows, audit logs, policy enforcement" },
+    ],
+    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"] },
+    ],
+    static_pages: {
+      features: "https://ateam-ai.com/#features",
+      use_cases: "https://ateam-ai.com/#usecases",
+      security: "https://ateam-ai.com/#security",
+      engine: "https://ateam-ai.com/#engine",
+    },
+    assistant_behavior_contract: {
+      first_run_requirements: [
+        "Explain platform before endpoints",
+        "Frame as AI Team solution platform",
+        "Give at least one example solution",
+        "Define Skill vs Solution vs Connector",
+        "Ask user what solution they want to build",
+      ],
+      thinking_order: ["Platform", "Solution", "Skills", "Connectors", "Governance", "Validation", "Deployment"],
+      tone: "Architectural, enterprise-grade, serious",
+      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_workflows: async () => get("/spec/workflows"),
+  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_examples: async ({ type }) => get(EXAMPLE_PATHS[type]),
+  adas_get_spec: async ({ topic }, sid) => get(SPEC_PATHS[topic], sid),
 
-  adas_validate_skill: async ({ skill }) => post("/validate/skill", { skill }),
+  adas_get_workflows: async (_args, sid) => get("/spec/workflows", sid),
 
-  adas_validate_solution: async ({ solution, skills }) =>
-    post("/validate/solution", { solution, skills }),
+  adas_get_examples: async ({ type }, sid) => get(EXAMPLE_PATHS[type], sid),
 
-  adas_deploy_solution: async ({ solution, skills, connectors, mcp_store }) =>
-    post("/deploy/solution", { solution, skills, connectors, mcp_store }),
+  adas_validate_skill: async ({ skill }, sid) => post("/validate/skill", { skill }, sid),
 
-  adas_deploy_skill: async ({ solution_id, skill }) =>
-    post(`/deploy/solutions/${solution_id}/skills`, { skill }),
+  adas_validate_solution: async ({ solution, skills }, sid) =>
+    post("/validate/solution", { solution, skills }, sid),
 
-  adas_deploy_connector: async ({ connector }) =>
-    post("/deploy/connector", { connector }),
+  adas_deploy_solution: async ({ solution, skills, connectors, mcp_store }, sid) =>
+    post("/deploy/solution", { solution, skills, connectors, mcp_store }, sid),
 
-  adas_list_solutions: async () => get("/deploy/solutions"),
+  adas_deploy_skill: async ({ solution_id, skill }, sid) =>
+    post(`/deploy/solutions/${solution_id}/skills`, { skill }, sid),
 
-  adas_get_solution: async ({ solution_id, view, skill_id }) => {
+  adas_deploy_connector: async ({ connector }, sid) =>
+    post("/deploy/connector", { connector }, sid),
+
+  adas_list_solutions: async (_args, sid) => get("/deploy/solutions", sid),
+
+  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`,
@@ -302,30 +430,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 {
@@ -333,14 +519,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,
     };
   }