MCP サーバービルダー

mcp-use フレームワークを使用してプロダクションレディな MCP サーバーを構築します。このスキルは MCP サーバー作成のためのクイックスタート手順とベストプラクティスを提供します。

クイックスタート

常に npx create-mcp-use-app でブートストラップ:

npx create-mcp-use-app my-mcp-server
cd my-mcp-server

ニーズに応じてテンプレートを選択:

• --template starter - すべての MCP プリミティブ (ツール、リソース、プロンプト) を含む全機能 + サンプルウィジェット
• --template mcp-apps - ChatGPT ウィジェット向けに最適化、商品検索の例付き
• --template blank - カスタム実装向けの最小限のスタート地点

# 例: MCP Apps テンプレート
npx create-mcp-use-app my-server --template mcp-apps
cd my-server
yarn install

テンプレートの詳細:

• starter: 学習向けの最適 - すべての MCP 機能とウィジェットを含む
• mcp-apps: ChatGPT アプリ向けの最適 - 商品カルーセル/アコーディオンの例を含む
• blank: エキスパート向けの最適 - 最小限のボイラープレート

MCP Apps の構造

自動ウィジェット登録

mcp-apps と starter テンプレートは、resources/ フォルダから React ウィジェットを自動的に検出および登録します:

単一ファイルウィジェットパターン:

resources/
└── weather-display.tsx  # ウィジェット名は "weather-display" になります

フォルダベースウィジェットパターン:

resources/
└── product-search/      # ウィジェット名は "product-search" になります
    ├── widget.tsx       # エントリポイント (必須の名前!)
    ├── components/      # サブコンポーネント
    ├── hooks/           # カスタムフック
    ├── types.ts
    └── constants.ts

自動的に行われること:

1. サーバーは起動時に resources/ フォルダをスキャン
2. .tsx ファイルまたはフォルダ内の widget.tsx を検出
3. 各コンポーネントから widgetMetadata を抽出
4. MCP ツールとして登録 (例: weather-display)
5. MCP リソースとして登録 (例: ui://widget/weather-display.html)
6. Vite でウィジェットバンドルをビルド

手動登録は不要! widgetMetadata をエクスポートしてデフォルトコンポーネントを定義するだけです。

ツールの定義

ツールは AI モデルが呼び出せる実行可能な関数です:

import { MCPServer, text, object } from "mcp-use/server";
import { z } from "zod";

const server = new MCPServer({
  name: "my-server",
  version: "1.0.0",
  description: "My MCP server"
});

// シンプルなツール
server.tool(
  {
    name: "greet-user",
    description: "Greet a user by name",
    schema: z.object({
      name: z.string().describe("The user's name"),
      formal: z.boolean().optional().describe("Use formal greeting")
    })
  },
  async ({ name, formal }) => {
    const greeting = formal ? `Good day, ${name}` : `Hey ${name}!`;
    return text(greeting);
  }
);

重要なポイント:

• Zod でスキーマ検証を使用
• すべてのパラメータに .describe() を追加
• 適切なレスポンスタイプを返す (text、object、widget)

リソースの定義

リソースはクライアントが読み込める データを公開します:

import { object, text, markdown } from "mcp-use/server";

// 静的リソース
server.resource(
  {
    uri: "config://settings",
    name: "Application Settings",
    description: "Current configuration",
    mimeType: "application/json"
  },
  async () => {
    return object({
      theme: "dark",
      version: "1.0.0"
    });
  }
);

// 動的リソース
server.resource(
  {
    uri: "stats://current",
    name: "Current Stats",
    description: "Real-time statistics",
    mimeType: "application/json"
  },
  async () => {
    const stats = await getStats();
    return object(stats);
  }
);

// Markdown リソース
server.resource(
  {
    uri: "docs://guide",
    name: "User Guide",
    description: "Documentation",
    mimeType: "text/markdown"
  },
  async () => {
    return markdown("# Guide\n\nWelcome!");
  }
);

利用可能なレスポンスヘルパー:

• text(string) - プレーンテキスト
• object(data) - JSON オブジェクト
• markdown(string) - Markdown コンテンツ
• html(string) - HTML コンテンツ
• image(buffer, mimeType) - バイナリ画像
• audio(buffer, mimeType) - オーディオファイル
• binary(buffer, mimeType) - バイナリデータ
• mix(...contents) - 複数のコンテンツタイプを結合

高度なレスポンス例:

// オーディオレスポンス
import { audio } from 'mcp-use/server';

// Base64 データから
return audio(base64Data, "audio/wav");

// ファイルパスから (非同期)
return await audio("/path/to/audio.mp3");

// バイナリデータ (PDF など)
import { binary } from 'mcp-use/server';
return binary(pdfBuffer, "application/pdf");

// 複数のコンテンツタイプを混在させる
import { mix, text, object, resource } from 'mcp-use/server';
return mix(
  text("Analysis complete:"),
  object({ score: 95, status: "pass" }),
  resource("report://analysis-123", text("Full report..."))
);

プロンプトの定義

プロンプトは AI インタラクション用の再利用可能なテンプレートです:

server.prompt(
  {
    name: "code-review",
    description: "Generate a code review template",
    schema: z.object({
      language: z.string().describe("Programming language"),
      focusArea: z.string().optional().describe("Specific focus area")
    })
  },
  async ({ language, focusArea }) => {
    const focus = focusArea ? ` with focus on ${focusArea}` : "";
    return {
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: `Please review this ${language} code${focus}.`
          }
        }
      ]
    };
  }
);

ローカルでのテスト

開発モード (ホットリロード):

yarn dev

プロダクションモード:

yarn build
yarn start

Inspector UI: http://localhost:3000/inspector でアクセスしてツールをテスト、リソースを表示、プロンプトを試すことができます。

トンネリング (デプロイ前に ChatGPT でテスト):

オプション 1 - 自動トンネル:

mcp-use start --port 3000 --tunnel

オプション 2 - 別々のトンネル:

yarn start  # ターミナル 1
npx @mcp-use/tunnel 3000  # ターミナル 2

https://happy-cat.local.mcp-use.run/mcp のような公開 URL が得られます

トンネルの詳細:

• 24 時間後に有効期限切れ
• 1 時間の不活動後にクローズ
• レート制限: 10 回/時間、IP あたり最大 5 つのアクティブ

詳細: https://mcp-use.com/docs/tunneling

デプロイ

mcp-use Cloud へのデプロイ (推奨):

# まずログイン (未実行の場合)
npx mcp-use login

# デプロイ
yarn deploy

認証エラーが発生した場合:

npx mcp-use login
yarn deploy

デプロイ後:

• 公開 URL が提供されます (例: https://your-server.mcp-use.com/mcp)
• 自動スケーリングと監視
• HTTPS が有効
• ゼロダウンタイムデプロイ

ベストプラクティス

ツール設計:

• ✅ 1 つのツール = 1 つの焦点を絞った機能
• ✅ 説明的な名前と説明
• ✅ すべての Zod フィールドで .describe() を使用
• ✅ エラーを適切に処理
• ✅ 有用なエラーメッセージを返す

リソース設計:

• ✅ クリアな URI スキームを使用 (config://、docs://、stats://)
• ✅ 適切な MIME タイプを選択
• ✅ レスポンスヘルパーを使用してコードを整理
• ✅ 必要に応じてリソースを動的にする

プロンプト設計:

• ✅ プロンプトは再利用可能に保つ
• ✅ コンテキストのためにシステムメッセージを使用
• ✅ Zod スキーマでパラメータ化
• ✅ 明確な指示を含める

テスト:

• ✅ まず Inspector UI でテスト
• ✅ デプロイ前に実際のクライアントでテストするためにトンネリングを使用
• ✅ すべてのツール、リソース、プロンプトが期待通りに機能することを確認

デプロイ:

• ✅ ローカルおよびトンネリングでまずテスト
• ✅ デプロイが失敗した場合は npx mcp-use login を実行
• ✅ サーバーをセマンティックにバージョニング
• ✅ 破壊的な変更をドキュメント化

ウィジェットサポート

自動ウィジェット登録

mcp-apps または starter テンプレートを使用する場合、resources/ フォルダ内のウィジェットが自動的に登録されます:

// resources/weather-display.tsx
import { useWidget, McpUseProvider, type WidgetMetadata } from 'mcp-use/react';
import { z } from 'zod';

const propSchema = z.object({
  city: z.string(),
  temperature: z.number()
});

// 必須: ウィジェットメタデータをエクスポート
export const widgetMetadata: WidgetMetadata = {
  description: "Display weather information",
  props: propSchema, // 'schema' ではなく 'props' を使用!
};

// 必須: デフォルトコンポーネントをエクスポート
export default function WeatherDisplay() {
  const { props, isPending } = useWidget<z.infer<typeof propSchema>>();
  
  // 常にローディング状態を処理
  if (isPending) return <div>Loading...</div>;
  
  return (
    <McpUseProvider autoSize>
      <div>
        <h2>{props.city}</h2>
        <p>{props.temperature}°C</p>
      </div>
    </McpUseProvider>
  );
}

ウィジェットは自動的に以下として利用可能になります:

• MCP ツール: weather-display
• MCP リソース: ui://widget/weather-display.html

Content Security Policy (CSP)

ウィジェットが外部リソースにアクセスできる内容を制御します:

export const widgetMetadata: WidgetMetadata = {
  description: "Weather widget",
  props: z.object({ city: z.string() }),
  metadata: {
    csp: {
      // 呼び出す API
      connectDomains: ["https://api.weather.com"],
      // ロードする静的アセット
      resourceDomains: ["https://cdn.weather.com"],
      // 埋め込む iframe
      frameDomains: ["https://embed.weather.com"],
      // スクリプトディレクティブ
      scriptDirectives: ["'unsafe-inline'"],
    },
  },
};

代わりに、サーバーレベルで設定します:

server.uiResource({
  type: "mcpApps",
  name: "my-widget",
  htmlTemplate: `...`,
  metadata: {
    csp: {
      connectDomains: ["https://api.example.com"],
      resourceDomains: ["https://cdn.example.com"],
    },
  },
});

デュアルプロトコルウィジェットサポート

mcp-use は MCP Apps 標準 (SEP-1865) を自動デュアルプロトコルサポートで対応しています:

import { MCPServer } from 'mcp-use/server';

const server = new MCPServer({
  name: 'my-server',
  version: '1.0.0',
  baseUrl: process.env.MCP_URL || 'http://localhost:3000', // ウィジェットに必須
});

// デュアルプロトコルウィジェットを登録
server.uiResource({
  type: "mcpApps", // MCP Apps クライアント AND ChatGPT の両方で機能
  name: "weather-display",
  htmlTemplate: `<!DOCTYPE html>...`,
  metadata: {
    csp: { connectDomains: ["https://api.weather.com"] },
    prefersBorder: true,
    autoResize: true,
  },
});

自動的に行われること:

• MCP Apps クライアント (Claude、Goose) は以下を受け取ります: _meta.ui.* を含む text/html;profile=mcp-app
• ChatGPT は以下を受け取ります: _meta.openai/* を含む text/html+skybridge
• 同じウィジェットコードがあらゆる場所で機能します!

カスタム OpenAI メタデータ

ChatGPT 固有の機能が必要ですか? 両方のメタデータフィールドを組み合わせます:

server.uiResource({
  type: "mcpApps",
  name: "my-widget",
  htmlTemplate: `...`,
  // 統一メタデータ (デュアルプロトコル)
  metadata: {
    csp: { connectDomains: ["https://api.example.com"] },
    prefersBorder: true,
  },
  // ChatGPT 固有のオーバーライド
  appsSdkMetadata: {
    "openai/widgetDescription": "ChatGPT-specific description",
    "openai/customFeature": "some-value", // カスタム OpenAI メタデータ
  },
});

プロジェクト構造

my-mcp-server/
├── resources/           # React ウィジェット (apps-sdk)
│   └── widget.tsx
├── public/             # 静的アセット
├── index.ts            # サーバーエントリポイント
├── package.json
├── tsconfig.json
└── README.md

一般的なパターン

デュアルプロトコルウィジェット付きツール:

import { MCPServer, widget, text } from 'mcp-use/server';
import { z } from 'zod';

const server = new MCPServer({
  name: 'my-server',
  version: '1.0.0',
  baseUrl: process.env.MCP_URL || 'http://localhost:3000',
});

server.tool(
  {
    name: "show-data",
    description: "Display data with visualization",
    schema: z.object({
      query: z.string()
    }),
    widget: {
      name: "data-display", // resources/ に存在する必要があります
      invoking: "Loading...",
      invoked: "Data loaded"
    }
  },
  async ({ query }) => {
    const data = await fetchData(query);
    return widget({
      props: { data },
      output: text(`Found ${data.length} results`)
    });
  }
);

リソーステンプレート (パラメータ化):

server.resourceTemplate(
  {
    uriTemplate: "user://{userId}/profile",
    name: "User Profile",
    description: "Get user by ID",
    mimeType: "application/json"
  },
  async ({ userId }) => {
    const user = await fetchUser(userId);
    return object(user);
  }
);

エラーハンドリング:

server.tool(
  {
    name: "divide",
    schema: z.object({
      a: z.number(),
      b: z.number()
    })
  },
  async ({ a, b }) => {
    if (b === 0) {
      return text("Error: Cannot divide by zero");
    }
    return text(`Result: ${a / b}`);
  }
);

詳細な例

包括的な例と高度なパターンについては、以下を提供する mcp-use MCP サーバー に接続してください:

• すべてのプリミティブの完全な例リソース
• フル動作するサーバーの例
• 詳細なドキュメント
• インタラクティブウィジェットショーケース

詳細情報

• ドキュメント: https://docs.mcp-use.com
• MCP Apps 標準: https://docs.mcp-use.com/typescript/server/mcp-apps (デュアルプロトコルガイド)
• テンプレート: https://docs.mcp-use.com/typescript/server/templates (テンプレート比較)
• ウィジェットガイド: https://docs.mcp-use.com/typescript/server/ui-widgets
• 例: https://github.com/mcp-use/mcp-use/tree/main/examples
• トンネリングガイド: https://mcp-use.com/docs/tunneling
• Discord: https://mcp-use.com/discord
• GitHub: https://github.com/mcp-use/mcp-use

クイックリファレンス

コマンド:

• npx create-mcp-use-app my-server - ブートストラップ
• yarn dev - 開発モード
• yarn build - プロダクション向けビルド
• yarn start - プロダクションサーバーを実行
• mcp-use start --tunnel - トンネル付きで起動
• npx mcp-use login - 認証
• yarn deploy - クラウドへデプロイ

レスポンスヘルパー:

• text(str)、object(data)、markdown(str)、html(str)
• image(buf, mime)、audio(buf, mime)、binary(buf, mime)
• mix(...) - 複数のコンテンツタイプを結合
• widget({ props, output }) - ウィジェットをデータ付きで返す

サーバーメソッド:

• server.tool() - 実行可能なツールを定義
• server.resource() - 静的/動的リソースを定義
• server.resourceTemplate() - パラメータ化されたリソースを定義
• server.prompt() - プロンプトテンプレートを定義
• server.uiResource() - ウィジェットリソースを定義
• server.listen() - サーバーを起動

ウィジェットメタデータフィールド:

• description - ウィジェットの説明
• props - ウィジェット props の Zod スキーマ
• metadata - 統一設定 (デュアルプロトコル)
• metadata.csp - Content Security Policy
• appsSdkMetadata - ChatGPT 固有のオーバーライド

利用可能なテンプレート:

• starter - 全機能 (ツール、リソース、プロンプト、ウィジェット)
• mcp-apps - ChatGPT 向けに最適化、商品の例付き
• blank - 最小限のボイラープレート