MCP SDK - AIアプリケーションと外部システムをつなぐ公式TypeScript SDK

はじめに

正直なところ、AIアプリケーションに外部データやツールを連携させるのって、結構面倒だったんですよ。

APIを叩くコードを書いて、認証を処理して、レスポンスをパースして...各サービスごとに異なる実装が必要で、コードが散らかりがちになる。そんな課題を解決してくれるのが**Model Context Protocol（MCP）**とその公式SDKです。

MCPは、いわばAIアプリケーション用の「USB-C」みたいなもの。電子機器をつなぐのにUSB-Cが標準化されているように、AIアプリケーションと外部システムをつなぐための標準規格という話です。

このMCP SDKはGitHubで10,900スター以上を獲得しており、Anthropicが公式にメンテナンスしています。

MCP SDKとは

MCP SDKは、Model Context Protocolのサーバーとクライアントを構築するための公式TypeScript SDKです。バージョン1.24.3（2025年12月時点）がリリースされており、143人のコントリビューターによって活発に開発が続いています。

このSDKを使えば、ClaudeやChatGPTなどのAIアプリケーションが以下のようなものにアクセスできるようになります：

• データソース: ローカルファイル、データベース、API
• ツール: 検索エンジン、計算機、外部サービス
• ワークフロー: 特化型プロンプト、自動化処理

これ、意外と革命的なんですよ。今まではAIモデルごとに異なる連携方法を実装する必要がありましたが、MCPを使えば一度の実装で様々なAIクライアントから利用できるようになります。

公式サイト: https://modelcontextprotocol.io GitHub: https://github.com/modelcontextprotocol/typescript-sdk

特徴・メリット

1. Anthropic公式の安心感

個人的にはこれが大きいですね。MCPはAnthropicが策定したオープン標準で、SDKも公式がメンテナンスしています。

ドキュメントも充実していて、更新も頻繁。10時間前にも更新があるくらい活発に開発されています。

2. サーバー・クライアント両対応

MCPサーバー（データやツールを提供する側）とMCPクライアント（AIアプリケーション側）の両方を構築できます。

// サーバー側：ツールやリソースを公開
const server = new McpServer({
  name: 'my-mcp-server',
  version: '1.0.0'
})

// クライアント側：サーバーに接続してツールを利用
const client = new Client({
  name: 'my-app',
  version: '1.0.0'
})

どちらの立場からでも実装できるのは便利です。

3. 複数のトランスポート対応

通信方式を柔軟に選べます：

• Streamable HTTP（推奨）: Webベースの統合に最適
• HTTP + SSE: 後方互換性のため
• stdio: ローカル統合やCLIツールに最適

用途に応じて使い分けられるのがいいですね。

4. ファーストクラスのTypeScript対応

SDKはTypeScriptで書かれていて、型安全に開発できます。Zodとの連携も標準でサポートされているので、バリデーションも型安全に書けます。

import { z } from 'zod'

// Zodスキーマで入力を定義
const inputSchema = z.object({
  query: z.string().min(1),
  limit: z.number().optional().default(10)
})

30代になって思うのは、型安全はQOLに直結するということ。実行時エラーで悩む時間が減ります。

5. 三種の神器：ツール・リソース・プロンプト

MCPサーバーは3種類の機能を公開できます：

機能	説明	ユースケース
ツール	LLMが実行可能なアクション	API呼び出し、計算、ファイル操作
リソース	読み取り専用データ	ファイル内容、DB参照、設定値
プロンプト	再利用可能なテンプレート	定型プロンプト、ワークフロー

この設計がよく考えられていて、必要な機能だけを公開できます。

インストール方法

基本インストール

npm install @modelcontextprotocol/sdk zod

ZodはピアDependencyとして必要です。Zod v3.25以降に対応していますが、内部的にはzod/v4を使用しています。

プロジェクトセットアップ

mkdir my-mcp-server
cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod typescript tsx
npx tsc --init

tsconfig.jsonで"module": "ESNext"と"moduleResolution": "bundler"を設定することを推奨します。

基本的な使い方

シンプルなMCPサーバー

import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { z } from 'zod'

// サーバーインスタンスを作成
const server = new McpServer({
  name: 'my-server',
  version: '1.0.0'
})

// ツールを登録：LLMが実行できるアクション
server.tool(
  'calculate',
  'Perform basic arithmetic',
  {
    operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
    a: z.number(),
    b: z.number()
  },
  async ({ operation, a, b }) => {
    let result: number
    switch (operation) {
      case 'add': result = a + b; break
      case 'subtract': result = a - b; break
      case 'multiply': result = a * b; break
      case 'divide': result = a / b; break
    }
    return {
      content: [{ type: 'text', text: `Result: ${result}` }]
    }
  }
)

// リソースを登録：読み取り専用データを公開
server.resource(
  'config',
  'config://app',
  async (uri) => ({
    contents: [{
      uri: uri.href,
      mimeType: 'application/json',
      text: JSON.stringify({ version: '1.0.0', debug: false })
    }]
  })
)

// サーバーを起動
const transport = new StdioServerTransport()
await server.connect(transport)

この例では、計算ツールと設定リソースを公開するシンプルなサーバーを作成しています。

MCPクライアント

import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'

// クライアントを作成
const client = new Client({
  name: 'my-client',
  version: '1.0.0'
})

// stdioでサーバーに接続
const transport = new StdioClientTransport({
  command: 'node',
  args: ['path/to/server.js']
})

await client.connect(transport)

// 利用可能なツールを取得
const tools = await client.listTools()
console.log('Available tools:', tools)

// ツールを実行
const result = await client.callTool({
  name: 'calculate',
  arguments: {
    operation: 'add',
    a: 5,
    b: 3
  }
})
console.log('Result:', result)

// リソースを読み取り
const resource = await client.readResource({
  uri: 'config://app'
})
console.log('Config:', resource)

Streamable HTTPサーバー

本番環境ではHTTPベースの通信が便利です。

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
import express from 'express'

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

const server = new McpServer({
  name: 'http-server',
  version: '1.0.0'
})

// ツールやリソースを登録...

// MCPエンドポイントを設定
app.post('/mcp', async (req, res) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined
  })

  res.on('close', () => {
    transport.close()
  })

  await server.connect(transport)
  await transport.handleRequest(req, res, req.body)
})

app.listen(3000, () => {
  console.log('MCP server running on http://localhost:3000')
})

実践的なユースケース

1. ファイルシステムアクセス

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { readFile, readdir } from 'fs/promises'
import { z } from 'zod'

const server = new McpServer({
  name: 'filesystem-server',
  version: '1.0.0'
})

// ファイル読み取りツール
server.tool(
  'read_file',
  'Read contents of a file',
  { path: z.string().describe('File path to read') },
  async ({ path }) => {
    const content = await readFile(path, 'utf-8')
    return {
      content: [{ type: 'text', text: content }]
    }
  }
)

// ディレクトリ一覧ツール
server.tool(
  'list_directory',
  'List files in a directory',
  { path: z.string().describe('Directory path') },
  async ({ path }) => {
    const files = await readdir(path)
    return {
      content: [{ type: 'text', text: files.join('\n') }]
    }
  }
)

これを使えば、Claudeがローカルファイルにアクセスしてコードレビューやドキュメント生成ができるようになります。

2. データベース連携

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { z } from 'zod'
import Database from 'better-sqlite3'

const db = new Database('app.db')

const server = new McpServer({
  name: 'database-server',
  version: '1.0.0'
})

// SQLクエリ実行ツール（読み取り専用）
server.tool(
  'query',
  'Execute a read-only SQL query',
  { sql: z.string().describe('SQL SELECT query') },
  async ({ sql }) => {
    // SELECT文のみ許可
    if (!sql.trim().toLowerCase().startsWith('select')) {
      return {
        content: [{ type: 'text', text: 'Error: Only SELECT queries are allowed' }],
        isError: true
      }
    }

    const results = db.prepare(sql).all()
    return {
      content: [{ type: 'text', text: JSON.stringify(results, null, 2) }]
    }
  }
)

// テーブル一覧リソース
server.resource(
  'tables',
  'db://tables',
  async () => {
    const tables = db.prepare(
      "SELECT name FROM sqlite_master WHERE type='table'"
    ).all()
    return {
      contents: [{
        uri: 'db://tables',
        mimeType: 'application/json',
        text: JSON.stringify(tables)
      }]
    }
  }
)

3. 外部API統合

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { z } from 'zod'

const server = new McpServer({
  name: 'weather-server',
  version: '1.0.0'
})

// 天気取得ツール
server.tool(
  'get_weather',
  'Get current weather for a city',
  {
    city: z.string().describe('City name'),
    country: z.string().optional().describe('Country code (e.g., JP)')
  },
  async ({ city, country }) => {
    const query = country ? `${city},${country}` : city
    const apiKey = process.env.WEATHER_API_KEY

    const response = await fetch(
      `https://api.openweathermap.org/data/2.5/weather?q=${query}&appid=${apiKey}&units=metric`
    )
    const data = await response.json()

    return {
      content: [{
        type: 'text',
        text: `${data.name}: ${data.main.temp}°C, ${data.weather[0].description}`
      }]
    }
  }
)

4. プロンプトテンプレート

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { z } from 'zod'

const server = new McpServer({
  name: 'prompts-server',
  version: '1.0.0'
})

// コードレビュープロンプト
server.prompt(
  'code_review',
  'Generate a code review prompt',
  { language: z.string().describe('Programming language') },
  async ({ language }) => ({
    messages: [{
      role: 'user',
      content: {
        type: 'text',
        text: `Please review the following ${language} code. Focus on:
1. Code quality and best practices
2. Potential bugs or edge cases
3. Performance considerations
4. Security concerns

Provide specific, actionable feedback.`
      }
    }]
  })
)

Claude Desktopとの連携

Claude Desktopを使っているなら、作成したMCPサーバーを設定ファイルで登録できます。

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/my-server.js"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    }
  }
}

設定ファイルの場所：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

注意点

1. セキュリティ

MCPサーバーはファイルシステムやデータベースにアクセスできるので、セキュリティには注意が必要です。

• 信頼できるソースからのリクエストのみ受け付ける
• 読み取り専用操作を基本にする
• 機密データへのアクセスは制限する

2. まだ発展途上

MCPは比較的新しいプロトコルなので、エコシステムはまだ成長中です。公式のサーバー実装（ファイルシステム、Git、PostgreSQLなど）はありますが、サードパーティ実装は少なめ。

3. デバッグ

開発時はMCP Inspectorを使うと便利です：

npx @modelcontextprotocol/inspector node path/to/server.js

ブラウザでツールやリソースをテストできます。

まとめ

正直なところ、MCP SDKは「AIアプリケーションと外部システムの連携」を考えているなら試す価値ありですね。

以下の条件に当てはまるなら、検討してみてください：

• ClaudeやChatGPTにカスタムツールを追加したい
• 社内システムやデータベースをAIと連携させたい
• 複数のAIクライアントで同じ機能を使いまわしたい
• AIエージェントの開発に興味がある

個人的には、特にClaude Codeとの組み合わせが強力だと感じています。ファイルシステムアクセスやGit操作など、開発効率が格段に上がります。

10,900スター以上という数字と、Anthropic公式という信頼性。AIツール連携の標準化が進む中、MCPを学んでおいて損はないと思います。

公式サイト: https://modelcontextprotocol.io GitHub: https://github.com/modelcontextprotocol/typescript-sdk NPM: @modelcontextprotocol/sdk