MCP Middleware Adapter for Express Servers

Express サーバー向け MCP ミドルウェアアダプター

• Express.js を使用して MCP (Model Context Protocol) サーバーを作成するための軽量アダプターです。

• https://tixaeagents.ai の提供により、MCP サーバーと互換性のあるテキスト／音声 AI エージェントを数秒で作成できます。

チェックリスト：

• SSE に対応した Express ミドルウェア統合
• WebSocket 統合への対応（近日対応予定ですが、SSE は問題なく動作しています）
• TypeScript に対応したツールの実装
• ヘッダーベースの認証に対応
• 異なるエンドポイントで複数の MCP クライアントを使用
• プロンプトへの対応（あまり必要性がないため、近日対応予定）

理由

• チャットをホストするメインの LLM サービスとは別に、MCP クライアントを個別にスケールアップ／ダウンしたり（すべて軽量ならグループ化したり）することはできません。1 台のサーバーで 100 人が npx を使って Playwright、Brave などの MCP を直接起動すると、メモリを大量に消費し、パフォーマンスのボトルネックになりやすいためです。
• 多数の MCP サーバーをデプロイ、更新、保守する既定の方法は面倒なため、それを簡素化することを目指しています。

インストール

npm install mcp-express-adapter@latest
# or
yarn add mcp-express-adapter@latest
# or
pnpm add mcp-express-adapter@latest

注：プライベートリポジトリからインストールする場合は、GitHub Packages で認証する必要があります。詳しくは GitHub Packages のドキュメントをご覧ください。

はじめに

Express サーバーで MCP クライアントを作成します（例）。

// examples/with-express/src/super-simple.ts
import express from 'express'
import cors from 'cors'
import { MCPClient, mcpTool } from 'mcp-express-adapter'
import { z } from 'zod'

// Create Express app
const app = express()
app.use(cors())

// Define a super simple weather tool
const weatherTool = mcpTool({
  name: 'get_weather',
  description: 'Get weather for a location',
  // Define input schema
  schema: z.object({
    location: z.string().describe('The city to get weather for'),
  }),
  // No output schema needed for simple string responses
  handler: async (args) => {
    // Just return a string - mcpTool handles the formatting
    return `Weather for ${args.location}: ☀️ Sunny and 72°F`
  },
})

// Create MCP client
const mcpClient = new MCPClient({
  endpoint: '/mcp',
  tools: [weatherTool],
  serverName: 'demo-server',
  serverVersion: '1.0.0',
})

// Mount MCP router
app.use('/mcp', mcpClient.middleware())

// Apply JSON parser for other routes
app.use(express.json())

// Start the server
const PORT = process.env.PORT || 3000
app.listen(PORT, () => {
  console.log(`✨ Super Simple MCP Server running!`)
  console.log(`🔗 Connect at: http://localhost:${PORT}/mcp/sse`)
})

ターミナルでサーバーが実行中であることを確認します：

MCP Client created with the following configuration:
- Endpoint: /mcp
- Server: my-mcp-server v1.0.0
- Tools: get_weather, calculator, generate_list, greeting
MCP Server running on port 3000
Connect at: http://localhost:3000/mcp/sse
Debug mode: enabled will show debug logs, to disable set NODE_ENV=production

これで Claude desktop で MCP サーバーをテストできます

• 設定 > 開発者 > 設定ファイルを編集し、以下のようにします：

{
  "mcpServers": {
    "localMcpServer": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-express-adapter",
        "--host",
        "http://localhost:3000/mcp/sse"
      ]
    }
  }
}

その後、Claude desktop を再起動すると、数秒以内に MCP ツールが表示されます。

同じ Express サーバー上で複数の MCP クライアントを使用する

// examples/with-express/src/multiple-mcp-clients.ts
import express from 'express'
import cors from 'cors'
import { MCPClient, mcpTool } from 'mcp-express-adapter'
import { z } from 'zod'

// Create Express app
const app = express()
app.use(cors())

// Define weather tool using mcpTool helper
const weatherTool = mcpTool({
  name: 'get_weather',
  description: 'Get the current weather for a location',
  schema: z.object({
    location: z.string().describe('The location to get weather for'),
  }),
  // you can define typesafe output schema..
  outputSchema: z.object({
    farenheight: z.number().describe('The temperature in farenheight'),
    celsius: z.number().describe('The temperature in celsius'),
  }),
  handler: async (args) => {
    return {
      farenheight: 72,
      celsius: 22,
    }
  },
})

// Define calculator tool using mcpTool helper
const calculatorTool = mcpTool({
  name: 'calculate',
  description: 'Calculate the result of a mathematical expression',
  schema: z.object({
    expression: z.string().describe('The mathematical expression to evaluate'),
  }),
  handler: async (args) => {
    return `Result: ${eval(args.expression)}`
  },
})

// Define time tool using mcpTool helper
const timeTool = mcpTool({
  name: 'get_time',
  description: 'Get the current time, optionally for a specific timezone',
  schema: z.object({
    timezone: z
      .string()
      .optional()
      .describe('The timezone to get time for (optional)'),
  }),
  handler: async (args) => {
    return `Current time${args.timezone ? ` in ${args.timezone}` : ''}: ${new Date().toLocaleString()}`
  },
})

// Create first MCP client with weather tool
const weatherClient = new MCPClient({
  endpoint: '/weather-mcp',
  tools: [weatherTool],
  serverName: 'weather-mcp-server',
  serverVersion: '1.0.0',
})

// Create second MCP client with calculator tool
const calculatorClient = new MCPClient({
  endpoint: '/calculator-mcp',
  tools: [calculatorTool],
  serverName: 'calculator-mcp-server',
  serverVersion: '1.0.0',
})

// Create third MCP client with time tool
const timeClient = new MCPClient({
  endpoint: '/time-mcp',
  tools: [timeTool],
  serverName: 'time-mcp-server',
  serverVersion: '1.0.0',
})

// Mount MCP routers BEFORE global JSON parser
app.use('/weather-mcp', weatherClient.middleware())
app.use('/calculator-mcp', calculatorClient.middleware())
app.use('/time-mcp', timeClient.middleware())

// Apply global JSON parser AFTER agent routes
app.use(express.json())

// Start the server
const PORT = process.env.PORT ? parseInt(process.env.PORT) : 3000
app.listen(PORT, () => {
  console.log(`Multiple MCP Servers running on port ${PORT}`)
  console.log(`Weather MCP: http://localhost:${PORT}/weather-mcp/sse`)
  console.log(`Calculator MCP: http://localhost:${PORT}/calculator-mcp/sse`)
  console.log(`Time MCP: http://localhost:${PORT}/time-mcp/sse`)
})

Langchain + Langgraph での使用

• @langchain/mcp-adapters を使用します https://github.com/langchain-ai/langchainjs-mcp-adapters

// examples/with-langchain/src/index.ts
import { MultiServerMCPClient } from '@langchain/mcp-adapters'
import { ChatAnthropic } from '@langchain/anthropic'
import { createReactAgent } from '@langchain/langgraph/prebuilt' // Incorrect
import dotenv from 'dotenv'

dotenv.config()

async function runLangchainMcpExample() {
  console.log('Initializing LangChain with MCP Adapters...')

  const model = new ChatAnthropic({
    model: 'claude-3-5-sonnet-20240620',
    temperature: 0,
    anthropicApiKey: process.env.ANTHROPIC_API_KEY,
  })

  // Keep constructor with only mcpServers map
  const mcpClient = new MultiServerMCPClient({
    googleMapsServer: {
      // The server map directly
      transport: 'sse',
      url: 'http://localhost:3000/mcp/sse',
      useNodeEventSource: true,
      reconnect: {
        enabled: true,
        maxAttempts: 3,
        delayMs: 1000,
      },
    },
  })

  console.log('Loading tools from MCP server via express adapter...')
  // Keep getTools call with options
  const tools = (await Promise.race([
    mcpClient.getTools(),
    new Promise((_, reject) =>
      setTimeout(
        () =>
          reject(new Error('Timeout: Failed to load tools within 15 seconds')),
        15000,
      ),
    ),
  ])) as Awaited<ReturnType<typeof mcpClient.getTools>>

  if (tools.length === 0) {
    console.error('No tools were loaded...')
    await mcpClient.close()
    return
  }

  console.log(
    `Loaded ${tools.length} tools:`,
    tools.map((t) => t.name).join(', '),
  )

  const agent = await createReactAgent({
    llm: model,
    tools,
  })

  const messages = [
    {
      role: 'system',
      content:
        'You are a helpful assistant. Use tools to answer user questions.',
    },
    {
      role: 'user',
      content: `What is the current weather in San Francisco?`,
    },
  ]
  let inputs = { messages }
  // console.log(`ALL GOOD NOW TART EVEN STREAMM>>!: `, inputs);
  // await new Promise((resolve) => setImmediate(resolve));
  const eventStream = await agent.streamEvents(inputs, {
    version: 'v2',
    //  signal: localController.signal, // <--- critical to pass localController!
  })

  // --- Invocation remains the same ---
  for await (const event of eventStream) {
    if (event.event === 'on_chat_model_stream') {
      console.log('Chat model stream')
      console.log(event.data.chunk.content[0]?.text)
    } else if (event.event === 'on_tool_start') {
      console.log('Tool start')
      console.log(JSON.stringify(event, null, 2))
    } else if (event.event === 'on_tool_end') {
      console.log('Tool end')
      console.log(JSON.stringify(event, null, 2))
    }
  }

  // console.log("\nClosing MCP client connections...");
  // await mcpClient.close();
  // console.log("MCP client closed.");
  // throw new Error("Test error");
}

runLangchainMcpExample()

例

型安全なツールを使った基本的な例

Zod スキーマを使って型安全な MCP ツールを作成する mcpTool ヘルパーの完全な使用例です：

// examples/with-express/src/index.ts
import express from 'express'
import cors from 'cors'
import { MCPClient, mcpTool } from 'mcp-express-adapter'
import { z } from 'zod'
import dotenv from 'dotenv'

// Load environment variables
dotenv.config()

// Create Express app
const app = express()
app.use(cors())

// Define weather tool using the enhanced mcpTool helper
const weatherTool = mcpTool({
  name: 'get_weather',
  description: 'Get the current weather for a location',
  schema: z.object({
    location: z.string().describe('The location to get weather for'),
  }),
  // Define the output schema
  outputSchema: z
    .object({
      temperature: z.number().describe('Current temperature in °F'),
      condition: z.string().describe('Weather condition (e.g., Sunny, Rainy)'),
      humidity: z.number().describe('Humidity percentage'),
      location: z.string().describe('The location this weather is for'),
    })
    .describe('Weather information for the requested location'),
  // Simply return the data - mcpTool handles the MCP formatting
  handler: async (args) => {
    console.log(`[WeatherTool] Called with location: ${args.location}`)
    // Return an object matching our output schema
    return {
      temperature: 72,
      condition: 'Sunny',
      humidity: 45,
      location: args.location,
    }
  },
})

// Add a calculator tool with a simple numeric output
const calculatorTool = mcpTool({
  name: 'calculator',
  description: 'Calculate the sum of two numbers',
  schema: z.object({
    a: z.number().describe('First number'),
    b: z.number().describe('Second number'),
  }),
  // Output is just a number
  outputSchema: z.number().describe('The sum of the two input numbers'),
  // Simply return the sum - no need to format for MCP
  handler: async (args) => {
    console.log(`[CalculatorTool] Called with: ${args.a}, ${args.b}`)
    return args.a + args.b
  },
})

// Add a tool that returns an array
const listTool = mcpTool({
  name: 'generate_list',
  description: 'Generate a list of items based on a category',
  schema: z.object({
    category: z
      .string()
      .describe('Category to generate items for (e.g., fruits, colors)'),
    count: z
      .number()
      .optional()
      .describe('Number of items to generate (default: 3)'),
  }),
  // Output is an array of strings
  outputSchema: z
    .array(z.string())
    .describe('List of generated items in the category'),
  handler: async (args) => {
    const count = args.count || 3
    console.log(
      `[ListTool] Generating ${count} items for category: ${args.category}`,
    )

    // Sample data based on category
    const items: Record<string, string[]> = {
      fruits: ['apple', 'banana', 'orange', 'grape', 'strawberry'],
      colors: ['red', 'blue', 'green', 'yellow', 'purple'],
      animals: ['dog', 'cat', 'elephant', 'tiger', 'penguin'],
    }

    const categoryItems = items[args.category.toLowerCase()] || [
      'item1',
      'item2',
      'item3',
      'item4',
      'item5',
    ]
    return categoryItems.slice(0, count)
  },
})

// Add a tool that doesn't specify an outputSchema (will expect string return)
const greetingTool = mcpTool({
  name: 'greeting',
  description: 'Get a personalized greeting',
  schema: z.object({
    name: z.string().describe('The name to greet'),
    formal: z.boolean().optional().describe('Whether to use formal language'),
  }),
  // No outputSchema needed, just return a string
  handler: async (args) => {
    const greeting = args.formal
      ? `Good day, ${args.name}. How may I be of service?`
      : `Hey ${args.name}! How's it going?`

    console.log(
      `[GreetingTool] Generated greeting for ${args.name} (formal: ${args.formal || false})`,
    )
    return greeting
  },
})

// Add a protected tool that checks for authentication
const protectedTool = mcpTool({
  name: 'get_passcode',
  description: 'Get the passcode for the user',
  schema: z.object({
    name: z.string().describe('The name of the user'),
  }),
  // Implement authentication check in the handler
  handler: async (args, context) => {
    console.log(`[ProtectedTool] Called with name: ${args.name}`)

    // Check for authorization header
    const authHeader = context?.headers?.authorization || ''
    console.log(context)
    console.log(`[ProtectedTool] Auth header: ${authHeader}`)

    // Check for bearer token that matches "000000"
    const validToken = 'Bearer 000000'
    if (!authHeader || authHeader !== validToken) {
      // Return error for unauthorized access
      throw new Error('Unauthorized: Invalid or missing authentication token')
    }

    // If authorized, return the protected data
    return `Protected data for ID: ${args.name}`
  },
})

// if true will show debug logs, to disable set NODE_ENV=production
const debugMode = process.env.NODE_ENV === 'development'

// Create MCP client
const mcpClient = new MCPClient({
  endpoint: '/mcp',
  tools: [weatherTool, calculatorTool, listTool, greetingTool, protectedTool],
  serverName: 'my-mcp-server',
  serverVersion: '1.0.0',
  debug: debugMode, // Enable debug logs only when --debug flag is passed
})

// Show metadata about the client
const metadata = mcpClient.getMetadata()
console.log('MCP Client created with the following configuration:')
console.log(`- Endpoint: ${metadata.endpoint}`)
console.log(`- Server: ${metadata.serverName} v${metadata.serverVersion}`)
console.log(`- Tools: ${metadata.tools.map((tool) => tool.name).join(', ')}`)

// Mount MCP router
app.use('/mcp', mcpClient.middleware())

// Apply JSON parser for other routes
app.use(express.json())

app.get('/', (req, res) => {
  res.send(`Hello World MCP Express Adapter.`)
})

// Start the server
const PORT = process.env.PORT ? parseInt(process.env.PORT) : 3000
app.listen(PORT, () => {
  const baseUrl = `http://localhost:${PORT}`

  // Get the SSE endpoint URL using the helper method
  const sseEndpoint = mcpClient.getSSEEndpoint(baseUrl)
  console.log(`MCP Client SSE Endpoint: ${sseEndpoint}`)

  console.log(
    `Debug mode: ${debugMode ? 'enabled will show debug logs, to disable set NODE_ENV=production' : 'disabled will not log anything.'}`,
  )
})

この例は次のコマンドで実行できます：

# From the root of the repo
pnpm install
pnpm test-express

ツール実装の例

mcpTool ヘルパーを使って簡単なツールを作成する方法は次のとおりです：

// examples/with-express/src/tool-example.ts
import { mcpTool } from 'mcp-express-adapter'
import { z } from 'zod'

/**
 * Example 1: Tool with an output schema for complex data
 *
 * Use this approach when your tool returns structured data that
 * needs strong type checking.
 */
const weatherTool = mcpTool({
  name: 'get_weather',
  description: 'Get the current weather for a location',
  schema: z.object({
    location: z.string().describe('The location to get weather for'),
  }),
  // Define the output schema for structured data
  outputSchema: z
    .object({
      temperature: z.number().describe('Current temperature in °F'),
      condition: z.string().describe('Weather condition (e.g., Sunny, Rainy)'),
      humidity: z.number().describe('Humidity percentage'),
      location: z.string().describe('The location this weather is for'),
    })
    .describe('Weather information for the requested location'),
  handler: async (args) => {
    // args.location is fully typed as string
    return {
      temperature: 72,
      condition: 'Sunny',
      humidity: 45,
      location: args.location,
    }
  },
})

/**
 * Example 2: Tool without an output schema for simple string responses
 *
 * Use this approach when your tool returns simple text responses
 * that don't need complex structure or validation.
 */
const greetingTool = mcpTool({
  name: 'greeting',
  description: 'Get a personalized greeting',
  schema: z.object({
    name: z.string().describe('The name to greet'),
    formal: z.boolean().optional().describe('Whether to use formal language'),
  }),
  // No outputSchema needed for simple string responses
  handler: async (args) => {
    // When no outputSchema is provided, you must return a string
    return args.formal
      ? `Good day, ${args.name}. How may I be of service?`
      : `Hey ${args.name}! How's it going?`
  },
})

// non typesafe tool:
// javascript ready
const nonTypesafeTool = {
  name: 'search_web',
  description: 'Search the web for information',
  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'The search query' },
      limit: {
        type: 'number',
        description: 'Maximum number of results to return',
      },
    },
    required: ['query'],
  },
  handler: async (args) => ({
    content: [
      {
        type: 'text',
        text: `Search results for "${args.query}": Results here...`,
      },
    ],
    isError: false,
  }),
}

export { weatherTool, greetingTool, nonTypesafeTool }

API リファレンス

MCPClient

Express サーバー上に MCP エンドポイントを作成するためのメインクラスです。

コンストラクターのオプション

interface MCPClientOptions {
  endpoint: string // The base path for the MCP endpoints
  tools: ToolImpl[] // Array of tool implementations
  serverName?: string // Optional server name (default: 'mcp-server')
  serverVersion?: string // Optional server version (default: '1.0.0')
}

ツールの実装

interface ToolImpl<T = any> {
  name: string // Tool name
  description: string // Tool description
  inputSchema: {
    // JSON Schema for the tool's input
    type: 'object'
    properties: Record<string, any>
    required?: string[]
  }
  handler: (
    args: T,
    context?: {
      headers?: Record<string, string> // Request headers accessible here
      [key: string]: any
    },
  ) => Promise<{
    content: Array<
      | { type: string; text?: string }
      | { type: string; data?: string; mimeType?: string }
    >
    isError?: boolean
  }>
}

ツール内でのヘッダーへのアクセス

context.headers オブジェクトを介して、ツールのハンドラー関数内でリクエストヘッダーにアクセスできます。これは、認証の実装、カスタムメタデータの受け渡し、その他のヘッダーベースのロジックに役立ちます。

クライアントが送信したヘッダー（たとえば、--header または --headers フラグを指定して mcp-express-adapter CLI を使用した場合）は、context から利用できます。

例：CLI で Authorization ヘッダーを渡す

Authorization: Bearer <token> ヘッダーを想定する保護されたツールを呼び出すには、CLI アダプターを次のように使用します：

# Using --header
npx mcp-express-adapter@latest --host http://localhost:3000/mcp/sse --header "Authorization: Bearer 000000"

# Using --headers (if passing multiple)
npx mcp-express-adapter@latest --host http://localhost:3000/mcp/sse --headers "Authorization: Bearer 000000, X-Custom: my-value"

例：Authorization ヘッダーを読み取るツール

context から Authorization ヘッダーを読み取る方法を示す protectedTool の例（examples/with-express/src/index.ts）です：

// Protected tool example with authentication
const protectedTool = mcpTool({
  name: 'get_passcode', // or 'protected_data' depending on your example version
  description: 'Get protected data (requires authentication)',
  schema: z.object({
    // ... input schema properties
    name: z.string().describe('The name of the user'), // Example property
  }),
  handler: async (args, context) => {
    // Access the headers from the context object
    // Node.js automatically lowercases header names
    const authHeader = context?.headers?.authorization || ''
    console.log(`[ProtectedTool] Auth header received: ${authHeader}`)

    // Validate the token (e.g., check for a specific Bearer token)
    const validToken = 'Bearer 000000'
    if (authHeader !== validToken) {
      throw new Error('Unauthorized: Invalid or missing authentication token')
    }

    // If authorized, proceed with tool logic
    console.log(`[ProtectedTool] Authorized access for user: ${args.name}`)
    return `Protected passcode for ${args.name}: 123456` // Return the protected data
  },
})

応用例

複数のツールとエンドポイントを使用する、より応用的な例です：

import express from 'express'
import cors from 'cors'
import { MCPClient } from 'mcp-express-adapter'

const app = express()
app.use(cors())

// Define multiple tools
const weatherTool = {
  name: 'get_weather',
  description: 'Get the current weather for a location',
  inputSchema: {
    type: 'object',
    properties: {
      location: { type: 'string', description: 'The location' },
    },
    required: ['location'],
  },
  handler: async (args) => ({
    content: [
      { type: 'text', text: `Weather for ${args.location}: Sunny, 72°F` },
    ],
    isError: false,
  }),
}

const searchTool = {
  name: 'search_web',
  description: 'Search the web for information',
  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'The search query' },
    },
    required: ['query'],
  },
  handler: async (args) => ({
    content: [
      {
        type: 'text',
        text: `Search results for "${args.query}": Results here...`,
      },
    ],
    isError: false,
  }),
}

// Set up multiple MCP Clients on different endpoints
const agent1 = new MCPClient({
  endpoint: '/agent-1',
  tools: [weatherTool, searchTool],
  serverName: 'mcp-server-agent-1',
  serverVersion: '1.0.0',
})

const agent2 = new MCPClient({
  endpoint: '/agent-2',
  tools: [weatherTool], // This agent only has weather tool
  serverName: 'mcp-server-agent-2',
  serverVersion: '1.0.0',
})

// Mount agent routers BEFORE global JSON parser
app.use('/agent-1', agent1.middleware())
app.use('/agent-2', agent2.middleware())

// Apply global JSON parser AFTER agent routes
app.use(express.json())

// Start the server
const PORT = 3000
app.listen(PORT, () => {
  console.log(`MCP Server running on port ${PORT}`)
  console.log(`Agent 1: http://localhost:${PORT}/agent-1/sse`)
  console.log(`Agent 2: http://localhost:${PORT}/agent-2/sse`)
})

MCP サーバーのテスト

curl を使って SSE エンドポイントに接続し、MCP サーバーをテストできます：

curl -N http://localhost:3000/mcp/sse

または、MCP コマンドラインクライアントを使用できます：

# Basic usage
npx mcp-express-adapter --host http://localhost:3000/mcp/sse

# With a single header
npx mcp-express-adapter --host http://localhost:3000/mcp/sse --header "Authorization: Bearer token123"

# With multiple headers (option 1: repeating --header)
npx mcp-express-adapter --host http://localhost:3000/mcp/sse --header "Authorization: Bearer token123" --header "X-Custom: Value"

# With multiple headers (option 2: comma-separated list)
npx mcp-express-adapter --host http://localhost:3000/mcp/sse --headers "Authorization: Bearer token123, X-Custom: Value"

よくある問題

• express.json() は MCP ミドルウェアを app.use に適用した後に適用してください。
• WebSocket はまだ十分にテストされていません。

コントリビューター

• Moe03 - 主なコントリビューターおよびメンテナー

貢献方法

貢献に興味がありますか？機能のリクエストやバグの報告は、GitHub リポジトリで issue を作成してください。

ライセンス

MIT