@dxos/mcp-client 0.8.3 → 0.8.4-main.422d1c7879

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/mcp-client",
-  "version": "0.8.3",
+  "version": "0.8.4-main.422d1c7879",
   "description": "MCP client.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -25,11 +25,11 @@
   "dependencies": {
     "@effect/ai": "0.33.2",
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "effect": "3.19.16",
-    "@dxos/ai": "0.8.3",
-    "@dxos/effect": "0.8.3",
-    "@dxos/invariant": "0.8.3",
-    "@dxos/log": "0.8.3"
+    "effect": "3.20.0",
+    "@dxos/ai": "0.8.4-main.422d1c7879",
+    "@dxos/effect": "0.8.4-main.422d1c7879",
+    "@dxos/invariant": "0.8.4-main.422d1c7879",
+    "@dxos/log": "0.8.4-main.422d1c7879"
   },
   "publishConfig": {
     "access": "public"

package/src/McpToolkit.test.ts

@@ -10,8 +10,9 @@ import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 import * as Schema from 'effect/Schema';
 
-import { AiService, type GenericToolkit } from '@dxos/ai';
+import { AiService, type OpaqueToolkit } from '@dxos/ai';
 import { TestAiService } from '@dxos/ai/testing';
+import { runAndForwardErrors } from '@dxos/effect';
 import { TestHelpers } from '@dxos/effect/testing';
 import { log } from '@dxos/log';
 
@@ -25,6 +26,26 @@ const AiServiceLayer = AiService.model('@anthropic/claude-opus-4-6', { thinking:
   ),
 );
 
+describe('connectWithFallback', () => {
+  it(
+    'connects to Linear MCP (SSE kind falls back to HTTP)',
+    {
+      skip: !process.env.LINEAR_API_KEY,
+      timeout: 30_000,
+    },
+    async () => {
+      const toolkit = await runAndForwardErrors(
+        McpToolkit.make({
+          url: 'https://mcp.linear.app/mcp',
+          kind: 'sse',
+          apiKey: process.env.LINEAR_API_KEY,
+        }),
+      );
+      log.info('connected', { tools: Object.keys(toolkit.toolkit.tools) });
+    },
+  );
+});
+
 describe('Browser Automation', () => {
   it.effect(
     'smoke',
@@ -37,7 +58,7 @@ describe('Browser Automation', () => {
 
         const chat = yield* Chat.empty;
         let prompt: Prompt.RawInput = 'Check that you are able to use the browser. Open https://example.com';
-        let output: LanguageModel.GenerateTextResponse<GenericToolkit.GenericTools>;
+        let output: LanguageModel.GenerateTextResponse<OpaqueToolkit.OpaqueTools>;
 
         do {
           output = yield* chat
@@ -59,7 +80,9 @@ describe('Browser Automation', () => {
       TestHelpers.provideTestContext,
       TestHelpers.taggedTest('llm'),
     ),
-    { timeout: 120_000 },
+    {
+      timeout: 120_000,
+    },
   );
 
   it.effect(
@@ -74,7 +97,7 @@ describe('Browser Automation', () => {
         const chat = yield* Chat.empty;
         let prompt: Prompt.RawInput =
           'Scrape effect blog at https://effect.website/blog and find the content of last 3 articles. Next prompt I will ask you generate structured representation.';
-        let output: LanguageModel.GenerateTextResponse<GenericToolkit.GenericTools>;
+        let output: LanguageModel.GenerateTextResponse<OpaqueToolkit.OpaqueTools>;
 
         do {
           output = yield* chat
@@ -118,6 +141,8 @@ describe('Browser Automation', () => {
       TestHelpers.provideTestContext,
       TestHelpers.taggedTest('llm'),
     ),
-    { timeout: 120_000 },
+    {
+      timeout: 120_000,
+    },
   );
 });

package/src/McpToolkit.ts

@@ -2,6 +2,8 @@
 // Copyright 2026 DXOS.org
 //
 
+// @import-as-namespace
+
 import * as Tool from '@effect/ai/Tool';
 import * as Toolkit from '@effect/ai/Toolkit';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
@@ -10,47 +12,39 @@ import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/
 import * as Effect from 'effect/Effect';
 import * as Schema from 'effect/Schema';
 
-import { GenericToolkit } from '@dxos/ai';
+import { OpaqueToolkit } from '@dxos/ai';
 import { invariant } from '@dxos/invariant';
 
 export interface McpToolkitOptions {
   url: string;
   kind: 'sse' | 'http';
+  apiKey?: string;
 }
 
 /**
- * Creates a GenericToolkit that connects to an MCP server and exposes its tools to the assistant.
+ * Creates an OpaqueToolkit that connects to an MCP server and exposes its tools to the assistant.
  *
  * @param options MCP server URL and transport kind ('sse' for SSE, 'http' for Streamable HTTP).
- * @returns A GenericToolkit containing all tools from the MCP server.
+ * @returns An OpaqueToolkit containing all tools from the MCP server.
  */
-export const make = (options: McpToolkitOptions): Effect.Effect<GenericToolkit.GenericToolkit> =>
+const CLIENT_INFO = { name: '@dxos/mcp-client', version: '0.8.3' };
+
+export const make = (options: McpToolkitOptions): Effect.Effect<OpaqueToolkit.OpaqueToolkit> =>
   Effect.gen(function* () {
-    const transport = createTransport(options.url, options.kind);
-    const client = new Client({ name: '@dxos/mcp-client', version: '0.8.3' });
-    yield* Effect.promise(() => client.connect(transport));
+    const client = yield* connectWithFallback(options);
 
     const { tools } = yield* Effect.promise(() => client.listTools());
-
     if (tools.length === 0) {
-      return GenericToolkit.empty;
+      return OpaqueToolkit.empty;
     }
 
     const effectTools = tools.map((mcpTool) => {
       const parameters: any = {};
       for (const [key, value] of Object.entries(mcpTool.inputSchema.properties ?? {})) {
         if (mcpTool.inputSchema.required?.includes(key)) {
-          parameters[key] = Schema.Unknown.pipe(
-            Schema.annotations({
-              jsonSchema: value,
-            }),
-          );
+          parameters[key] = Schema.Unknown.pipe(Schema.annotations({ jsonSchema: value }));
         } else {
-          parameters[key] = Schema.Unknown.pipe(
-            Schema.annotations({
-              jsonSchema: value,
-            }),
-          ).pipe(Schema.optional);
+          parameters[key] = Schema.Unknown.pipe(Schema.annotations({ jsonSchema: value })).pipe(Schema.optional);
         }
       }
 
@@ -84,22 +78,58 @@ export const make = (options: McpToolkitOptions): Effect.Effect<GenericToolkit.G
 
     const layer = toolkit.toLayer(handlers);
 
-    return GenericToolkit.make(toolkit, layer);
+    return OpaqueToolkit.make(toolkit, layer);
   }).pipe(Effect.withSpan('McpToolkit.make'));
 
+/**
+ * Returns true when the error (or its wrapped cause) contains a 405 status code.
+ * `Effect.tryPromise` wraps thrown errors in `UnknownException`, so we unwrap first.
+ */
+export const is405 = (error: unknown): boolean => {
+  const cause = error != null && typeof error === 'object' && 'error' in error ? (error as any).error : error;
+  return cause instanceof Error && cause.message.includes('405');
+};
+
+/**
+ * Connects to an MCP server, falling back to the alternate transport on 405 errors.
+ * Per the MCP spec, a 405 indicates the server uses the other transport protocol.
+ * Returns the connected Client (a fresh instance is created for the fallback attempt).
+ */
+const connectWithFallback = (options: McpToolkitOptions): Effect.Effect<Client> =>
+  Effect.gen(function* () {
+    const fallbackKind = options.kind === 'sse' ? 'http' : 'sse';
+    const primary = yield* connectClient(options.url, options.kind, options.apiKey).pipe(Effect.either);
+    if (primary._tag === 'Right') {
+      return primary.right;
+    }
+    if (is405(primary.left)) {
+      return yield* connectClient(options.url, fallbackKind, options.apiKey).pipe(Effect.orDie);
+    }
+    return yield* Effect.die(primary.left);
+  });
+
+const connectClient = (url: string, kind: McpToolkitOptions['kind'], apiKey?: string) =>
+  Effect.tryPromise(() => {
+    const client = new Client(CLIENT_INFO);
+    const transport = createTransport(url, kind, apiKey);
+    return client.connect(transport).then(() => client);
+  });
+
 /**
  * Creates a transport for the given MCP server URL and kind.
  */
 const createTransport = (
   url: string,
   kind: McpToolkitOptions['kind'],
+  apiKey?: string,
 ): SSEClientTransport | StreamableHTTPClientTransport => {
   const urlObj = new URL(url);
+  const requestInit: RequestInit | undefined = apiKey ? { headers: { Authorization: `Bearer ${apiKey}` } } : undefined;
   switch (kind) {
     case 'sse':
-      return new SSEClientTransport(urlObj);
+      return new SSEClientTransport(urlObj, { requestInit });
     case 'http':
-      return new StreamableHTTPClientTransport(urlObj);
+      return new StreamableHTTPClientTransport(urlObj, { requestInit });
     default: {
       const _exhaustive: never = kind;
       return invariant(false, `Unsupported MCP transport kind: ${_exhaustive}`) as never;
@@ -125,5 +155,6 @@ const formatToolResult = (result: Awaited<ReturnType<Client['callTool']>>): stri
       .map((part) => part.text)
       .join('\n');
   }
+
   return String(result);
 };

package/src/is405.test.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Cause from 'effect/Cause';
+import { describe, test } from 'vitest';
+
+import * as McpToolkit from './McpToolkit';
+
+describe('is405', () => {
+  test('matches raw Error with 405 in message', ({ expect }) => {
+    expect(McpToolkit.is405(new Error('SSE error: Non-200 status code (405)'))).toBe(true);
+  });
+
+  test('matches UnknownException wrapping a 405 Error', ({ expect }) => {
+    const wrapped = new Cause.UnknownException(new Error('SSE error: Non-200 status code (405)'));
+    expect(McpToolkit.is405(wrapped)).toBe(true);
+  });
+
+  test('does not match unrelated errors', ({ expect }) => {
+    expect(McpToolkit.is405(new Error('connection refused'))).toBe(false);
+  });
+
+  test('does not match UnknownException wrapping a non-405 Error', ({ expect }) => {
+    const wrapped = new Cause.UnknownException(new Error('connection refused'));
+    expect(McpToolkit.is405(wrapped)).toBe(false);
+  });
+
+  test('does not match null or undefined', ({ expect }) => {
+    expect(McpToolkit.is405(null)).toBe(false);
+    expect(McpToolkit.is405(undefined)).toBe(false);
+  });
+});