@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/mcp-server-form.ts

@@ -0,0 +1,233 @@
+/**
+ * Refusals, wire bodies, the read shape and the comparison for `LiteLLM.MCPServer`, testable
+ * without a server. The URL rules are in `mcp-server-url.ts`.
+ *
+ * ⛔ TWO ACCESS GRANTS ARE ALWAYS COMPARED, WITH A CLOSED DEFAULT. `allow_all_keys` (default
+ *   false) and `mcp_access_groups` (default empty) decide which keys can reach a server, so a live
+ *   value that differs from the declaration is corrected rather than left as it is.
+ * ⛔ `allowed_tools` IS NOT ONE OF THEM: it is compared and sent ONLY WHEN DECLARED, like `alias`.
+ *   An empty list is the OPEN state, not a closed one. Measured on the live 1.103.0 container:
+ *   `server_applies_tool_allowlist` (`mcp_server/utils.py`) is "the `mcp_info` enforce flag, or a
+ *   non-empty `allowed_tools`", and `filter_tools_by_allowed_tools` (`server.py` lines 1692-1698)
+ *   returns every tool when it is false. This resource does not model `mcp_info`, so a default of
+ *   `[]` would switch a live whitelist OFF the moment a row is adopted without restating it, and an
+ *   adopted row is planned `adopted` (Alchemy's adoption branch), so no `update` would show. An
+ *   undeclared list is left exactly as the proxy holds it.
+ * ★ Descriptive fields (`alias`, `description`) are also compared only when declared, so adopting a
+ *   row never clears text a person wrote. That holds on the wire too, for `alias` only because an
+ *   update RE-SENDS the live alias whenever it sends a `serverName` (`identityOnUpdate` below).
+ * ⚠️ EVERY UPDATE SENDS THE FULL MANAGED SET, NOT ONLY THE FIELDS THAT DIFFER, bar the two name
+ *   fields, which `identityOnUpdate` sends selectively because LiteLLM defaults an alias. The edit
+ *   route is a PARTIAL update at 1.103.0 (measured by reading the live container's
+ *   `mcp_server/db.py`, the update function's `exclude_unset=True`: fields the caller did not send
+ *   keep their stored value; no live call was made), so a field this resource does not send is left
+ *   alone. Sending the whole managed set is still correct, and reconcile reads back and fails loudly
+ *   if a declared field did not land (`LitellmMcpServerNotConvergedError`). Whether a `false` or an
+ *   empty list is written rather than skipped stays UNMEASURED, which is what the read back guards.
+ */
+import type * as mcp from '@distilled.cloud/litellm/mcp_management';
+import * as Redacted from 'effect/Redacted';
+import { redactUrl, urlProblem } from './mcp-server-url.ts';
+import {
+  AUTH_TYPES,
+  type McpServerAttributes,
+  type McpServerProps,
+  TRANSPORTS,
+  isBlank,
+  isStaticAuthType,
+} from './mcp-server-types.ts';
+
+const listProblem = (name: string, list: readonly unknown[] | undefined): string | undefined =>
+  list !== undefined && list.some((entry) => isBlank(entry))
+    ? `\`${name}\` must hold non-empty strings`
+    : undefined;
+
+/**
+ * ⛔ LITELLM 1.103 RUNS THE MCP SDK'S `validate_tool_name` ON `server_name` AND THE NORMALISED
+ *   ALIAS, and that 400 happens only at apply. The names it accepts are `^[A-Za-z0-9._]{1,128}$`:
+ *   a space, `/`, `:`, `@`, or more than 128 characters is refused here so nothing is written to
+ *   Alchemy's state first. `-` is out for the same reason and one more: it is
+ *   `MCP_TOOL_PREFIX_SEPARATOR` (default `-`, unset in the live container as measured 2026-09-29),
+ *   and a tool is `<alias>-<tool>`. A proxy that set another separator would be over-refused:
+ *   rare, and loud. `normalize_server_name` would also rewrite a space to `_`, so a name outside
+ *   this pattern would never equal the row it produced.
+ */
+const TOOL_NAME = /^[A-Za-z0-9._]{1,128}$/;
+
+const toolNameProblem = (field: string, value: string): string | undefined =>
+  TOOL_NAME.test(value)
+    ? undefined
+    : `\`${field}\` must match ^[A-Za-z0-9._]{1,128}$: LiteLLM 1.103 rejects a space, "/", ":", "@", "-" or more than 128 characters only at apply`;
+
+/** A declared alias is a tool name too. Omitted is fine: the live alias is kept. */
+const aliasProblem = (alias: string | undefined): string | undefined => {
+  if (alias === undefined) return undefined;
+  if (isBlank(alias)) return '`alias` must be a non-empty string when declared';
+  return toolNameProblem('alias', alias);
+};
+
+/** The first reason a declaration is refused, or `undefined`. Pure: no environment, no server. */
+export const firstProblem = (props: McpServerProps): string | undefined => {
+  if (isBlank(props.serverName) || props.serverName !== props.serverName.trim()) {
+    return '`serverName` must be a non-empty string without leading or trailing whitespace';
+  }
+  const named = toolNameProblem('serverName', props.serverName) ?? aliasProblem(props.alias);
+  if (named !== undefined) return named;
+  // ⛔ A blank description never converges. LiteLLM copies the column into `mcp_info` only when
+  //   the value is truthy (`build_mcp_server_from_table`), and the list then answers
+  //   `mcp_info.description`. `''` is written and read back as absent, so every deploy would fail
+  //   the read back. Omitted is still "leave the live text alone".
+  if (props.description !== undefined && isBlank(props.description)) {
+    return '`description` must be a non-empty string when declared: LiteLLM copies it into mcp_info only when it is truthy, so a blank one never converges';
+  }
+  if (props.serverId !== undefined && isBlank(props.serverId)) {
+    return '`serverId` must be a non-empty string when declared';
+  }
+  const url = urlProblem(props.url);
+  if (url !== undefined) return url;
+  if (!TRANSPORTS.includes(props.transport)) {
+    return '`transport` must be "sse" or "http" (`stdio` runs a command on the proxy host and is not modelled)';
+  }
+  if (!AUTH_TYPES.includes(props.authType)) {
+    return `\`authType\` must be one of ${AUTH_TYPES.join(', ')}; the others need credential fields this resource does not model`;
+  }
+  const declared = props.authValue !== undefined;
+  if (isStaticAuthType(props.authType) && !declared) {
+    return `\`authType: "${props.authType}"\` needs \`authValue: { fromEnv: … }\``;
+  }
+  if (!isStaticAuthType(props.authType) && declared) {
+    return `\`authValue\` is the static credential for api_key, bearer_token, basic, authorization and token; this server is "${props.authType}"`;
+  }
+  if (declared && isBlank(props.authValue?.fromEnv)) {
+    return '`authValue.fromEnv` must name an environment variable';
+  }
+  return (
+    listProblem('allowedTools', props.allowedTools) ??
+    listProblem('mcpAccessGroups', props.mcpAccessGroups)
+  );
+};
+
+/**
+ * One row of `GET /v1/mcp/server`, or of the by-id read, as attributes.
+ *
+ * ⚠️ THE LIST'S `description` IS `mcp_info.description` WHEN THAT EXISTS, else the column (measured
+ *   on the live 1.103.0 container: `_build_mcp_server_table` and, on registration,
+ *   `build_mcp_server_from_table`, which copies the column into `mcp_info` only when `mcp_info`
+ *   has none). This resource writes only the column, so a declared description cannot be read back
+ *   from a row whose `mcp_info` holds another: reconcile refuses that before it writes.
+ *
+ * ⛔ `credentials`, `static_headers`, `env`, `env_vars` and every other field are deliberately NOT
+ *   copied: what LiteLLM stores as a credential stays on the proxy. The `credentialSeal` is filled
+ *   in by the caller from the previous state; a row cannot supply one.
+ */
+export const toAttributes = (row: mcp.LiteLLMMCPServerTable): McpServerAttributes => ({
+  alias: row.alias ?? null,
+  allowAllKeys: row.allow_all_keys ?? false,
+  allowedTools: [...(row.allowed_tools ?? [])],
+  authType: row.auth_type ?? 'none',
+  credentialSeal: '',
+  description: row.description ?? null,
+  mcpAccessGroups: [...(row.mcp_access_groups ?? [])],
+  serverId: row.server_id,
+  serverName: row.server_name ?? null,
+  transport: row.transport,
+  url: row.url === undefined || row.url === null ? null : redactUrl(row.url),
+});
+
+const sameSet = (live: readonly string[], declared: readonly string[]): boolean =>
+  new Set(live).size === new Set(declared).size && declared.every((entry) => live.includes(entry));
+
+/** Wire names of the fields where the live row and the declaration disagree. */
+export const differing = (live: McpServerAttributes, props: McpServerProps): readonly string[] => {
+  const out: string[] = [];
+  if (live.serverName !== props.serverName) out.push('server_name');
+  if (live.url !== props.url) out.push('url');
+  if (live.transport !== props.transport) out.push('transport');
+  if (live.authType !== props.authType) out.push('auth_type');
+  if (live.allowAllKeys !== (props.allowAllKeys ?? false)) out.push('allow_all_keys');
+  if (props.allowedTools !== undefined && !sameSet(live.allowedTools, props.allowedTools)) {
+    out.push('allowed_tools');
+  }
+  if (!sameSet(live.mcpAccessGroups, props.mcpAccessGroups ?? [])) out.push('mcp_access_groups');
+  if (props.alias !== undefined && live.alias !== props.alias) out.push('alias');
+  if (props.description !== undefined && live.description !== props.description) {
+    out.push('description');
+  }
+  return out;
+};
+
+/** The managed set both writes send, WITHOUT the name fields. ⚠️ See the file header on why an update sends all of it. */
+const managed = (props: McpServerProps) => ({
+  allow_all_keys: props.allowAllKeys ?? false,
+  ...(props.allowedTools === undefined ? {} : { allowed_tools: [...props.allowedTools] }),
+  auth_type: props.authType,
+  ...(props.description === undefined ? {} : { description: props.description }),
+  mcp_access_groups: [...(props.mcpAccessGroups ?? [])],
+  transport: props.transport,
+  url: props.url,
+});
+
+/** A create names the row, and sends an alias only when one is declared: LiteLLM defaults it to the name. */
+const identityOnCreate = (props: McpServerProps) => ({
+  ...(props.alias === undefined ? {} : { alias: props.alias }),
+  server_name: props.serverName,
+});
+
+/**
+ * ⛔ AN UPDATE MUST NOT LET LITELLM DEFAULT THE ALIAS. Measured 2026-09-29 by running the live
+ *   1.103.0 container's own `validate_and_normalize_mcp_server_payload` and `_prepare_mcp_server_data`
+ *   on an edit body (no database, no network): a body with a `server_name` and no `alias` comes out
+ *   with `alias = normalize(server_name)` and the alias IS WRITTEN, because the route captures the
+ *   set of fields the caller sent BEFORE the normalisation and `_prepare_mcp_server_data` drops an
+ *   alias only when it is still None. The alias is the tool prefix (`get_server_prefix`), so a row
+ *   with alias `search` and name `estate_web` would have every tool renamed `estate_web-*` for
+ *   every key and seat, while `differing` (which skips an undeclared alias) called it converged.
+ *   A body with neither field sends no alias. So:
+ *   - `server_name` is sent only when it CHANGES, and
+ *   - an alias is sent when declared, or (on a rename) as the live one, so a rename keeps the prefix.
+ *   A live row with no alias that is renamed gets the new name as its alias: LiteLLM's own default.
+ */
+const identityOnUpdate = (props: McpServerProps, live: McpServerAttributes) => {
+  const renamed = live.serverName !== props.serverName;
+  const alias = props.alias ?? (renamed && live.alias !== null ? live.alias : undefined);
+  return {
+    ...(alias === undefined ? {} : { alias }),
+    ...(renamed ? { server_name: props.serverName } : {}),
+  };
+};
+
+/**
+ * ⛔ THE ONE PLACE THE CREDENTIAL IS UNWRAPPED, and it goes straight onto the wire body. `undefined`
+ *   sends no `credentials` key at all, which leaves whatever LiteLLM already holds.
+ */
+const credentialsOf = (credential: Redacted.Redacted<string> | undefined) =>
+  credential === undefined ? {} : { credentials: { auth_value: Redacted.value(credential) } };
+
+export const createBody = (
+  props: McpServerProps,
+  serverId: string,
+  credential: Redacted.Redacted<string> | undefined,
+): mcp.AddMcpServerV1McpServerPostRequest => ({
+  ...managed(props),
+  ...identityOnCreate(props),
+  ...credentialsOf(credential),
+  server_id: serverId,
+});
+
+/**
+ * `clearCredentials` sends an explicit `credentials: null`, for a server moving off a static auth
+ * type. Whether LiteLLM clears its stored credential on `null` or ignores it (an `exclude_none`
+ * merge) is UNMEASURED at 1.103.0; either way nothing is sent that could set a wrong one.
+ */
+export const updateBody = (
+  props: McpServerProps,
+  serverId: string,
+  credential: Redacted.Redacted<string> | undefined,
+  clearCredentials: boolean,
+  live: McpServerAttributes,
+): mcp.EditMcpServerV1McpServerPutRequest => ({
+  ...managed(props),
+  ...identityOnUpdate(props, live),
+  ...(clearCredentials ? { credentials: null } : credentialsOf(credential)),
+  server_id: serverId,
+});

package/src/litellm/mcp-server-handlers.test.ts

@@ -0,0 +1,150 @@
+/**
+ * `LiteLLM.MCPServer`'s handlers and operations called directly, for what the engine harness cannot
+ * show: that nothing a proxy returns can reach an attribute, and that delete is idempotent by a
+ * real read.
+ *
+ * ⚠️ CALLING A HANDLER DIRECTLY IS NOT THE SHAPE THE ENGINE USES for a create-first replace
+ *   (`output: undefined, olds: undefined` under a fresh instance id) — that path is
+ *   `mcp-server.test.ts`, through `fakeStack`. What is checked here does not depend on it.
+ * ★ EVERY VALUE IS `FAKE-*`.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { credentials } from '@distilled.cloud/litellm/Credentials';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { FAKE_BASE } from './fake-litellm.ts';
+import { serverRow, startFakeMcpLitellm } from './fake-mcp-litellm.ts';
+import { mcpServerHandlers } from './mcp-server.ts';
+import { deleteMcpServer, listMcpServers } from './mcp-server-operations.ts';
+import type { McpServerProps } from './mcp-server-types.ts';
+
+const KEY = 'sk-test-master';
+const VARIABLE = 'FAKE_MCP_HANDLER_TOKEN';
+
+/**
+ * ⚠️ `R` IS `unknown` BECAUSE `reconcile`'s type still names `InstanceId | Stack | Stage`, which
+ *   `createPhysicalName` needs and a declared `serverId` never reaches; the cast below is the same
+ *   one `pass-through-endpoint-delete-swallow.test.ts` makes.
+ */
+const run = <A, E>(
+  fetchFn: typeof globalThis.fetch,
+  effect: Effect.Effect<A, E, unknown>,
+): Promise<A> =>
+  Effect.runPromise(
+    effect.pipe(
+      Effect.provide(FetchHttpClient.layer),
+      Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fetchFn)),
+      Effect.provide(credentials({ apiKey: KEY, baseUrl: FAKE_BASE })),
+    ) as Effect.Effect<A, E, never>,
+  );
+
+const props: McpServerProps = {
+  authType: 'bearer_token',
+  authValue: { fromEnv: VARIABLE },
+  serverName: 'FAKE_docs',
+  transport: 'http',
+  url: 'https://mcp.example.com/mcp',
+};
+
+beforeEach(() => {
+  process.env[VARIABLE] = 'FAKE-handler-secret';
+});
+afterEach(() => {
+  delete process.env[VARIABLE];
+});
+
+describe('reading a server never reveals auth material', () => {
+  // ⚠️ the fake's worst case: a proxy whose list hands every stored secret back
+  const leaky = serverRow({
+    credentials: { auth_value: 'FAKE-live-secret' },
+    env_vars: [{ name: 'FAKE_ENV', scope: 'global', value: 'FAKE-env-secret' }],
+    server_id: 'FAKE-uuid-1',
+    server_name: 'FAKE_docs',
+    static_headers: { Authorization: 'FAKE-header-secret' },
+    url: 'https://mcp.example.com/mcp?token=FAKE-url-secret',
+  });
+
+  test('read of an adopted row: no credential, header, env value or url token in the attributes', async () => {
+    const fake = startFakeMcpLitellm({ echoCredentials: true, masterKey: KEY, seed: [leaky] });
+    const read = await run(
+      fake.fetch,
+      mcpServerHandlers.read({ id: 'Docs', instanceId: 'i', olds: props, output: undefined }),
+    );
+    const text = JSON.stringify(read);
+    for (const secret of [
+      'FAKE-live-secret',
+      'FAKE-env-secret',
+      'FAKE-header-secret',
+      'FAKE-url-secret',
+    ]) {
+      expect(text).not.toContain(secret);
+    }
+    expect(text).toContain('REDACTED');
+  });
+
+  test('reconcile: the attributes hold a seal, never the credential it sent', async () => {
+    const fake = startFakeMcpLitellm({ echoCredentials: true, masterKey: KEY });
+    // ⚠️ `serverId` declared: a direct call has no Stack for `createPhysicalName` to read.
+    const attributes = await run(
+      fake.fetch,
+      mcpServerHandlers.reconcile({
+        id: 'Docs',
+        instanceId: 'i',
+        news: { ...props, serverId: 'FAKE-uuid-2' },
+        output: undefined,
+      }),
+    );
+    expect(JSON.stringify(attributes)).not.toContain('FAKE-handler-secret');
+    expect(attributes.credentialSeal).toStartWith('scrypt:');
+    // ★ the credential did reach the proxy — that is the write — and only there
+    expect(fake.servers()[0]?.['credentials']).toEqual({ auth_value: 'FAKE-handler-secret' });
+  });
+
+  test('the sealed variable name is the only thing the declaration holds', () => {
+    expect(JSON.stringify(props)).not.toContain('FAKE-handler-secret');
+  });
+});
+
+describe('list', () => {
+  test('answers the rows from a bare array', async () => {
+    const fake = startFakeMcpLitellm({
+      masterKey: KEY,
+      seed: [serverRow({ server_id: 'FAKE-1' })],
+    });
+    expect((await run(fake.fetch, listMcpServers())).map((row) => row.server_id)).toEqual([
+      'FAKE-1',
+    ]);
+  });
+
+  test('refuses an answer that is not a list of servers', async () => {
+    const notAList = (async () =>
+      new Response(JSON.stringify({ detail: 'nope' }), {
+        headers: { 'content-type': 'application/json' },
+      })) as unknown as typeof globalThis.fetch;
+    await expect(run(notAList, listMcpServers())).rejects.toThrow();
+  });
+});
+
+describe('delete', () => {
+  const row = serverRow({ server_id: 'FAKE-uuid-1', server_name: 'FAKE_docs' });
+
+  test('removes a live row', async () => {
+    const fake = startFakeMcpLitellm({ masterKey: KEY, seed: [row] });
+    await run(fake.fetch, deleteMcpServer('FAKE-uuid-1'));
+    expect(fake.servers()).toEqual([]);
+  });
+
+  test('an id already gone is done, confirmed by a table read (mcp-server-registry.test.ts)', async () => {
+    const fake = startFakeMcpLitellm({ masterKey: KEY });
+    await expect(run(fake.fetch, deleteMcpServer('FAKE-never'))).resolves.toBeUndefined();
+  });
+
+  test('a delete refused for another reason is not swallowed: it fails and the row is live', async () => {
+    // ⚠️ the fake answers 400 to every DELETE — the status of "no rights" is unmeasured on the
+    //   real route, which is exactly why a read of the table, not the status, decides.
+    const fake = startFakeMcpLitellm({ forbidDelete: true, masterKey: KEY, seed: [row] });
+    await expect(run(fake.fetch, deleteMcpServer('FAKE-uuid-1'))).rejects.toThrow();
+    expect(fake.servers()).toHaveLength(1);
+  });
+});

package/src/litellm/mcp-server-locate.ts

@@ -0,0 +1,66 @@
+/**
+ * Which live row a `LiteLLM.MCPServer` declaration means, and which id a new row would ask for.
+ *
+ * ⛔ THE LIST DECIDES FIRST, THE DATABASE SECOND. `GET /v1/mcp/server` is LiteLLM's in-memory
+ *   registry, not the table (mcp-server-operations.ts says how a committed row can be missing from
+ *   it). A row the list does not show is therefore looked for BY ID in the database, with the id
+ *   this declaration would use. Without that second read, a row created a moment ago whose
+ *   registry refresh failed would be POSTed again: the id is deterministic, LiteLLM answers 400
+ *   "already exists", and the resource would be wedged on a row it can neither see nor adopt.
+ * ⚠️ ADOPT-BY-NAME NEEDS THE LIST: a name cannot be read from the table by this route family. A row
+ *   the registry lacks is adoptable only by declaring its `serverId`.
+ */
+import type * as mcp from '@distilled.cloud/litellm/mcp_management';
+import { createPhysicalName } from 'alchemy/PhysicalName';
+import * as Effect from 'effect/Effect';
+import { LitellmMcpServerAmbiguousNameError } from './mcp-server-errors.ts';
+import { listMcpServers, readMcpServer } from './mcp-server-operations.ts';
+import type { McpServerAttributes, McpServerProps } from './mcp-server-types.ts';
+
+/**
+ * The live row among the LISTED ones, or `undefined`. A pinned id (from state, else declared) wins;
+ * otherwise the name decides, and an ambiguous name is refused.
+ */
+export const locate = (
+  rows: readonly mcp.LiteLLMMCPServerTable[],
+  props: McpServerProps,
+  output: McpServerAttributes | undefined,
+) => {
+  const pinned = output?.serverId ?? props.serverId;
+  if (pinned !== undefined) return Effect.succeed(rows.find((row) => row.server_id === pinned));
+  const named = rows.filter((row) => row.server_name === props.serverName);
+  return named.length > 1
+    ? Effect.fail(
+        new LitellmMcpServerAmbiguousNameError({
+          serverIds: named.map((row) => row.server_id),
+          serverName: props.serverName,
+        }),
+      )
+    : Effect.succeed(named[0]);
+};
+
+/** The id a create asks for: the recorded one, else the declared one, else a deterministic name. */
+export const wantedId = (
+  id: string,
+  instanceId: string,
+  props: McpServerProps,
+  output: McpServerAttributes | undefined,
+) =>
+  output?.serverId !== undefined
+    ? Effect.succeed(output.serverId)
+    : props.serverId !== undefined
+      ? Effect.succeed(props.serverId)
+      : createPhysicalName({ id, instanceId, lowercase: true, maxLength: 64 });
+
+/** The live row this declaration means, from the list, else from the table by the id it would use. */
+export const findLive = (
+  id: string,
+  instanceId: string,
+  props: McpServerProps,
+  output: McpServerAttributes | undefined,
+) =>
+  Effect.gen(function* () {
+    const listed = yield* locate(yield* listMcpServers(), props, output);
+    if (listed !== undefined) return listed;
+    return yield* readMcpServer(yield* wantedId(id, instanceId, props, output));
+  });

package/src/litellm/mcp-server-operations.ts

@@ -0,0 +1,111 @@
+/**
+ * The five LiteLLM `/v1/mcp/server*` calls `LiteLLM.MCPServer` uses, through the SDK's typed
+ * operations in `@distilled.cloud/litellm/mcp_management` (LiteLLM 1.103.0):
+ *
+ *   list    `fetchAllMcpServersV1McpServerGet`          GET    /v1/mcp/server
+ *   read    `fetchMcpServerV1McpServerServerIdGet`      GET    /v1/mcp/server/{server_id}
+ *   create  `addMcpServerV1McpServerPost`               POST   /v1/mcp/server
+ *   update  `editMcpServerV1McpServerPut`               PUT    /v1/mcp/server
+ *   delete  `removeMcpServerV1McpServerServerIdDelete`  DELETE /v1/mcp/server/{server_id}
+ *
+ * ⛔ THE LIST IS NOT THE TABLE. Measured 2026-09-29 by reading the live 1.103.0 container:
+ *   `GET /v1/mcp/server` answers `global_mcp_server_manager`'s IN-MEMORY REGISTRY
+ *   (`_resolve_accessible_mcp_servers`), not `LiteLLM_MCPServerTable`. `reload_servers_from_database`
+ *   loads only rows whose approval status is null, active or approved, and skips a row whose build
+ *   throws; the registry is narrowed again by the caller's key (`object_permission.mcp_servers`); and
+ *   `add_mcp_server` only LOGS a failed registry refresh after the row is committed. So a row that
+ *   is absent from the list can be live in the database. The list is right for adopt-by-name, and
+ *   wrong as proof of absence. The database is read by ID (`readMcpServer`): `fetch_mcp_server`
+ *   asks `get_mcp_server` (the table) first and answers 404 only when the table, the registry and
+ *   a name lookup all miss.
+ * ⚠️ THE BY-ID READ HAS SIDE EFFECTS, so it is used only where the list cannot decide: it registers
+ *   the row in the registry (`add_server`) and runs a health check against the upstream server.
+ * ⛔ NO MESSAGE SNIFFING. `mcp_management` declares only `UnprocessableEntity` beyond the shared
+ *   errors — the distilled `patches/` that type `BadRequest`/`NotFound` cover five other admin tags
+ *   (budget, key, team, internal_user, model), not this one. A 404 from these routes still decodes
+ *   at run time as the SDK's `NotFound` class (core's `HTTP_STATUS_MAP`), invisible to the type
+ *   checker; `readMcpServer` tests that class with `instanceof` and nothing else, and a REAL READ
+ *   decides (`deleteMcpServer`), the way `budget-operations.ts` and pass-through `operations.ts` do.
+ *   The typed fix is a distilled patch for this tag, which belongs in the distilled clone.
+ * ⚠️ Unlike pass-through endpoints, each server is its own DB row: no semaphore.
+ */
+import * as mcp from '@distilled.cloud/litellm/mcp_management';
+import { NotFound } from '@distilled.cloud/litellm/Errors';
+import * as Effect from 'effect/Effect';
+import { type LitellmOpContext, throughFetch } from './operations.ts';
+import { LitellmMcpServerUnreadableError } from './mcp-server-errors.ts';
+
+const hasServerId = (row: unknown): boolean =>
+  typeof row === 'object' &&
+  row !== null &&
+  typeof (row as { server_id?: unknown }).server_id === 'string';
+
+/** ⚠️ The REGISTRY as the caller may see it, not the table: see the file header. */
+export const listMcpServers = (): Effect.Effect<
+  readonly mcp.LiteLLMMCPServerTable[],
+  mcp.FetchAllMcpServersV1McpServerGetError | LitellmMcpServerUnreadableError,
+  LitellmOpContext
+> =>
+  throughFetch(mcp.fetchAllMcpServersV1McpServerGet({})).pipe(
+    // ⚠️ The SDK types the answer `{ body: LiteLLMMCPServerTable[] }`, but a top-level JSON array is
+    //   handed back as the array itself (measured through the fake, as for `/budget/list`). Accept
+    //   both shapes and refuse anything else.
+    Effect.flatMap((response) => {
+      const rows: unknown = Array.isArray(response)
+        ? response
+        : (response as { body?: unknown }).body;
+      return Array.isArray(rows) && rows.every(hasServerId)
+        ? Effect.succeed(rows as readonly mcp.LiteLLMMCPServerTable[])
+        : Effect.fail(
+            new LitellmMcpServerUnreadableError({
+              reason: Array.isArray(rows) ? 'a row has no server_id' : 'not an array',
+            }),
+          );
+    }),
+  );
+
+/**
+ * One row read BY ID, DATABASE FIRST, or `undefined` when the proxy has no such row.
+ *
+ * ★ THE ROW MUST CARRY THE ID ASKED FOR. When the table has no row, `fetch_mcp_server` falls back to
+ *   the registry and then to a lookup by NAME or alias, so an id that happens to be another server's
+ *   name answers THAT server. A row with another id is "no such row" here.
+ * ⛔ ANY FAILURE OTHER THAN `NotFound` PROPAGATES: a 401, a 500 or a dead network says nothing about
+ *   whether the row exists, and must never be read as absence.
+ */
+export const readMcpServer = (serverId: string) =>
+  throughFetch(mcp.fetchMcpServerV1McpServerServerIdGet({ server_id: serverId })).pipe(
+    Effect.map((row) => (row.server_id === serverId ? row : undefined)),
+    Effect.catch((error) =>
+      error instanceof NotFound ? Effect.succeed(undefined) : Effect.fail(error),
+    ),
+  );
+
+/** Answers the created row, which carries the `server_id` LiteLLM actually used. */
+export const createMcpServer = (body: mcp.AddMcpServerV1McpServerPostRequest) =>
+  throughFetch(mcp.addMcpServerV1McpServerPost(body));
+
+export const updateMcpServer = (body: mcp.EditMcpServerV1McpServerPutRequest) =>
+  throughFetch(mcp.editMcpServerV1McpServerPut(body)).pipe(Effect.asVoid);
+
+/**
+ * Idempotent BY THIS FUNCTION, not by the vendor. The DELETE is ALWAYS SENT: it acts on the table
+ * (`delete_mcp_server` answers 404 for a missing row), so a row the list does not show, because the
+ * registry dropped it, is still removed. A list that skipped the call for an unlisted id would drop
+ * Alchemy's state for a row that stays live in the database.
+ *
+ * If the DELETE fails, the failure is swallowed only when a DATABASE-BACKED read by id says the row is
+ * absent (`readMcpServer`: a concurrent removal, or a row already gone). A row that is still there,
+ * or a read that cannot say, re-raises the ORIGINAL error — so a delete refused for lack of rights,
+ * which leaves the row live, is never reported as done.
+ */
+export const deleteMcpServer = (serverId: string) =>
+  throughFetch(mcp.removeMcpServerV1McpServerServerIdDelete({ server_id: serverId })).pipe(
+    Effect.asVoid,
+    Effect.catch((original) =>
+      readMcpServer(serverId).pipe(
+        Effect.catch(() => Effect.fail(original)),
+        Effect.flatMap((row) => (row === undefined ? Effect.void : Effect.fail(original))),
+      ),
+    ),
+  );