feat: accept an org parameter on the execute tools

CLAUDE.md

@@ -27,6 +27,7 @@ A Model Context Protocol (MCP) server that exposes the Kosli API to LLM clients
 - ESM only (`"type": "module"`, `NodeNext` resolution). Relative imports must use `.js` extensions even though the source is `.ts`.
 - TypeScript `strict: true`. Don't weaken it.
 - The `org` path parameter falls back to `config.org` (from `KOSLI_ORG`). Preserve this in `KosliClient.buildUrl`.
+- A per-call org is interpreted in exactly one place: `normalizeOrg` + `orgError` in `src/tools/execute-action.ts`, which both execute tools go through (the `KOSLI_ORG` default never passes through them: `loadConfig` trims it and rejects a blank one at startup, and `KosliClient.buildUrl` falls back to it when a call names no org). The `org` tool input and `params.org` obey the same rules — trimmed, only a string names one (coercing would turn `["a", "b"]` into the org `a,b`), `null` means not supplied, blank rejected, an org on a non-org-scoped action rejected, and two different orgs in one call rejected rather than resolved, because the same path performs writes. Note the ordering: `params.org` is read *before* `unwrapBodyParam` and the body's org *after* it — the unwrap flattens a write's body over the top level, so reading only once lets the spread pick a winner and hides the disagreement. Keep that decision in the one place; don't re-implement it per tool in `index.ts`.
 - Errors from the Kosli API are returned as `{ error: true, status, statusText, message }` — not thrown. Tools stringify whatever they get. Keep this contract; the LLM handles the error object.
 - Responses are serialized with `JSON.stringify(result)` (compact, no pretty-printing) to minimize token usage. Don't revert to pretty-printing.
 - All API requests include `User-Agent: kosli-mcp-server/<version>` for server-side tracking, with the version coming from `VERSION` in `src/version.ts`. Preserve the header and keep the version in it — the backend uses it to tell releases apart.

README.md

@@ -32,7 +32,7 @@ The server reads configuration from environment variables:
 | Variable | Required | Default | Notes |
 |----------|----------|---------|-------|
 | `KOSLI_API_TOKEN` | yes | — | Preferred. `KOSLI_API_KEY` is accepted as a fallback. |
-| `KOSLI_ORG` | yes | — | Default org used when a path param `org` is not supplied. |
+| `KOSLI_ORG` | yes | — | Default org used when a call does not supply one. Trimmed; whitespace-only is rejected at startup. |
 | `KOSLI_BASE_URL` | no | `https://app.kosli.com` | EU (default), US (`https://app.us.kosli.com`), or your single-tenant endpoint. |
 
 ## Wire up to an MCP client
@@ -107,7 +107,38 @@ Typical LLM flow:
 > [!IMPORTANT]
 > `execute_write_action` creates, modifies, and deletes real resources in your Kosli organization. MCP clients gate these calls behind an approval prompt — read the action ID and parameters before approving. An LLM may select the wrong action, or the right action with the wrong parameters, and approval is the only checkpoint before the call is made. Treat deletions and anything touching service accounts or API keys with particular care.
 
-The `org` path parameter defaults to `KOSLI_ORG` if not supplied. For `GET`/`DELETE`, non-path params become query parameters; for other methods they become the JSON body.
+For `GET`/`DELETE`, non-path params become query parameters; for other methods they become the JSON body.
+
+### Working with more than one organization
+
+Both execute tools take an optional `org`, so a single running server can reach
+any organization your token has access to — useful when you are moving between
+orgs in one conversation rather than restarting the server for each:
+
+```json
+{ "actionId": "list_envs", "org": "cyber-dojo", "fields": ["name"] }
+```
+
+- Omit it and the call goes to `KOSLI_ORG`.
+- It applies to that one call. The next call goes back to `KOSLI_ORG`.
+- Surrounding whitespace is trimmed. A blank org is rejected rather than
+  quietly producing a URL with the organization missing from it.
+- One org, named as a string. Anything else is rejected rather than coerced,
+  because coercion turns a value that is not a name into one that looks like a
+  name: `["cyber-dojo", "kosli-public"]` would request the org
+  `cyber-dojo,kosli-public`, and an org id would request an org called `1234`.
+- Four actions are not organization-scoped (`get_user_default_org`,
+  `list_system_attestation_types`, and the two `/schemas/...` actions). Passing
+  an org to one of those is rejected rather than ignored, whether it arrives as
+  `org` or inside `params`.
+- There are three ways to name an org in one call: this input, `params.org`, and
+  an `org` inside a write's request body. They must agree; two different names
+  are rejected rather than resolved, because the same tools perform writes and
+  the target is never guessed.
+- An org your token cannot reach comes back as the usual error object carrying
+  the API's status — `403` for both an org you are not a member of and one that
+  does not exist. Note that Kosli staff accounts can read any org, so a
+  successful read does not prove a write would be permitted.
 
 Both execute tools accept an optional `fields` array to request only specific top-level fields from each object in the response. This dramatically reduces response size and token usage:
 

src/config.ts

@@ -6,9 +6,11 @@ export function loadConfig(): Config {
     throw new Error("KOSLI_API_TOKEN (or KOSLI_API_KEY) environment variable is required");
   }
 
-  const org = process.env.KOSLI_ORG;
+  // Trimmed so the existing check also catches a whitespace-only value, which
+  // is truthy and would otherwise become the org path segment on every call.
+  const org = process.env.KOSLI_ORG?.trim();
   if (!org) {
-    throw new Error("KOSLI_ORG environment variable is required");
+    throw new Error("KOSLI_ORG environment variable is required, and must not be blank");
   }
 
   const baseUrl = process.env.KOSLI_BASE_URL || "https://app.kosli.com";

src/index.ts

@@ -13,6 +13,11 @@ import { VERSION } from "./version.js";
 const entries = catalog as CatalogEntry[];
 const config = loadConfig();
 
+// Shared by both execute tools so the two can't drift apart.
+const ORG_INPUT = z.string().optional().describe(
+  `Kosli organization to run this call against, e.g. "cyber-dojo". Defaults to "${config.org}" (from KOSLI_ORG). It applies to this call only — the next call goes back to the default unless you set it again.`,
+);
+
 const server = new McpServer({
   name: "kosli",
   version: VERSION,
@@ -48,18 +53,19 @@ server.registerTool(
   "execute_read_action",
   {
     title: "Execute read action",
-    description: `Execute a read-only (GET) Kosli API action by its ID with the given parameters. Use search_actions first to find the action ID and required parameters. The 'org' parameter defaults to "${config.org}" — you do not need to supply it unless querying a different organization.`,
+    description: `Execute a read-only (GET) Kosli API action by its ID with the given parameters. Use search_actions first to find the action ID and required parameters. The call runs against the "${config.org}" organization unless you set 'org'.`,
     annotations: {
       readOnlyHint: true,
     },
     inputSchema: {
       actionId: z.string().describe("The action ID from search_actions results"),
+      org: ORG_INPUT,
       params: z.record(z.string(), z.unknown()).optional().default({}).describe("Parameters for the action (path params or query params)"),
       fields: z.array(z.string()).optional().describe("Only include these fields in each object of the response. Dramatically reduces response size. Example: [\"name\",\"compliant\",\"fingerprint\",\"reasons_for_incompliance\"]"),
     },
   },
-  async ({ actionId, params, fields }) => {
-    const result = await executeAction(entries, config, actionId, params, fields, undefined, "GET");
+  async ({ actionId, params, fields, org }) => {
+    const result = await executeAction(entries, config, actionId, params, fields, undefined, "GET", org);
     return {
       content: [
         {
@@ -75,19 +81,20 @@ server.registerTool(
   "execute_write_action",
   {
     title: "Execute write action",
-    description: `Execute a write (POST, PUT, PATCH, DELETE) Kosli API action by its ID with the given parameters. Use search_actions first to find the action ID and required parameters. The 'org' parameter defaults to "${config.org}" — you do not need to supply it unless querying a different organization.`,
+    description: `Execute a write (POST, PUT, PATCH, DELETE) Kosli API action by its ID with the given parameters. Use search_actions first to find the action ID and required parameters. The call runs against the "${config.org}" organization unless you set 'org' — check it before approving, the write lands in whichever org it names.`,
     annotations: {
       destructiveHint: true,
       readOnlyHint: false,
     },
     inputSchema: {
       actionId: z.string().describe("The action ID from search_actions results"),
+      org: ORG_INPUT,
       params: z.record(z.string(), z.unknown()).optional().default({}).describe("Parameters for the action (path params, query params, or body)"),
       fields: z.array(z.string()).optional().describe("Only include these fields in each object of the response. Dramatically reduces response size."),
     },
   },
-  async ({ actionId, params, fields }) => {
-    const result = await executeAction(entries, config, actionId, params, fields, undefined, "WRITE");
+  async ({ actionId, params, fields, org }) => {
+    const result = await executeAction(entries, config, actionId, params, fields, undefined, "WRITE", org);
     return {
       content: [
         {

src/tools/execute-action.ts

@@ -56,6 +56,60 @@ function unwrapBodyParam(
   return { ...rest, ...(body as Record<string, unknown>) };
 }
 
+/**
+ * The org a call is aimed at, as it will actually be used: trimmed, and
+ * `undefined` when nothing was supplied. `null` counts as nothing, matching
+ * `KosliClient.buildUrl`, which falls back to `config.org` on a nullish
+ * `params.org`. An empty string means "supplied, but unusable", which
+ * `orgError` turns into a rejection.
+ */
+function normalizeOrg(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  // Only a string can name an org. `params` is a record of `unknown`, so the
+  // model can put anything here, and coercing it would turn a value that is not
+  // a name into one that looks like a name: `["a", "b"]` reads as the org "a,b"
+  // and an org id reads as an org called "1234". Both would then pass the
+  // agreement check below as a single name. Hand back the unusable marker
+  // instead and let orgError say so.
+  if (typeof value !== "string") return "";
+  return value.trim();
+}
+
+/**
+ * Check the orgs a call names, returning a message when the request cannot be
+ * honoured as written. This is the only place the target org is decided, so
+ * both execute tools behave identically and every way of naming one obeys the
+ * same rules.
+ *
+ * `named` holds the distinct orgs the call mentions, already normalized. There
+ * are three ways to name one and they must agree: the `org` argument,
+ * `params.org`, and — for a write — an `org` inside the request body, which
+ * `unwrapBodyParam` flattens over the top level. Two different names are
+ * rejected rather than resolved: the same code path performs writes, and
+ * guessing wrong would write to the wrong organization.
+ */
+function orgError(entry: CatalogEntry, named: string[]): string | undefined {
+  const takesOrg = entry.parameters.some((p) => p.name === "org" && p.in === "path");
+  if (!takesOrg) {
+    if (named.length === 0) return undefined;
+    return `Action "${entry.id}" is not organization-scoped — it takes no org. Retry with no org in the org parameter, in params.org, or in the request body.`;
+  }
+
+  // Before any disagreement: an unusable value is the thing to report, and
+  // reporting it as a nameless org disagreeing with a real one would send the
+  // caller to drop one of the two rather than to fix the bad value.
+  if (named.includes("")) {
+    return "The org must be a single organization name, given as a non-empty string. Check the org parameter, params.org, and any org in the request body, or omit all of them to use the configured default.";
+  }
+
+  if (named.length > 1) {
+    const quoted = named.map((o) => `"${o}"`).join(" and ");
+    return `Conflicting orgs in one call: ${quoted}. The org parameter, params.org, and an org in the request body must agree — supply just one.`;
+  }
+
+  return undefined;
+}
+
 export async function executeAction(
   catalog: CatalogEntry[],
   config: Config,
@@ -64,6 +118,7 @@ export async function executeAction(
   fields?: string[],
   fetchFn: FetchFn = globalThis.fetch,
   mode?: ToolMode,
+  org?: string,
 ): Promise<unknown> {
   const entry = catalog.find((e) => e.id === actionId);
   if (!entry) {
@@ -84,8 +139,32 @@ export async function executeAction(
     };
   }
 
+  // Collect the org from every channel before deciding. `unwrapBodyParam`
+  // flattens a write's request body over the top level, so params.org has to be
+  // read before the unwrap and the body's org after it — otherwise the spread
+  // picks a winner and the disagreement is never seen. When the unwrap declines,
+  // `unwrapped` is `params` and the body's org is never read. That is correct:
+  // an unflattened body cannot reach the path, so there is nothing to check.
+  const beforeUnwrap = normalizeOrg(params.org);
+  const unwrapped = unwrapBodyParam(entry, params);
+  const named = [...new Set(
+    [normalizeOrg(org), beforeUnwrap, normalizeOrg(unwrapped.org)]
+      .filter((o): o is string => o !== undefined),
+  )];
+
+  const message = orgError(entry, named);
+  if (message) return { error: true, message };
+
+  // The checked value is the one that goes out, so buildUrl cannot see a
+  // different org from the one that was approved. With nothing named, the key
+  // is dropped rather than left as a null that would ride along as a stray
+  // query parameter.
+  const withOrg = { ...unwrapped };
+  if (named.length === 0) delete withOrg.org;
+  else withOrg.org = named[0];
+
   const client = new KosliClient(config, fetchFn);
-  const result = await client.execute(entry, unwrapBodyParam(entry, params));
+  const result = await client.execute(entry, withOrg);
 
   // Never strip error shapes — pickFields would reduce them to {}
   // and hide the failure from the LLM.