mcp-builder

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 - カスタム実装向けの最小構成のテンプレート

# Example: MCP Apps template
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  # Widget name becomes "weather-display"

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

resources/
└── product-search/      # Widget name becomes "product-search"
    ├── widget.tsx       # Entry point (required name!)
    ├── components/      # Sub-components
    ├── hooks/           # Custom 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"
});

// Simple tool
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() を追加します
• 適切なレスポンス型（テキスト、オブジェクト、ウィジェット）を返します

リソースの定義

リソースは、クライアントが読み取れるデータを公開します：

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

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

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

// Markdown resource
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) - 複数のコンテンツ型を組み合わせます

高度なレスポンスの例：

// Audio response
import { audio } from 'mcp-use/server';

// From base64 data
return audio(base64Data, "audio/wav");

// From file path (async)
return await audio("/path/to/audio.mp3");

// Binary data (PDFs, etc.)
import { binary } from 'mcp-use/server';
return binary(pdfBuffer, "application/pdf");

// Mix multiple content types
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

インスペクター UI： http://localhost:3000/inspector にアクセスすると、ツールのテスト、リソースの表示、プロンプトの試用ができます。

トンネリング（デプロイ前に ChatGPT でテスト）：

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

mcp-use start --port 3000 --tunnel

オプション 2 - 個別のトンネル：

yarn start  # Terminal 1
npx @mcp-use/tunnel 3000  # Terminal 2

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

トンネルの詳細：

• 24 時間後に有効期限が切れます
• 1 時間操作がないと閉じます
• レート制限：1 時間あたり 10 件作成、IP あたり最大 5 件をアクティブにできます

詳細はこちら：https://mcp-use.com/docs/tunneling

デプロイ

mcp-use Cloud にデプロイします（推奨）：

# Login first (if not already)
npx mcp-use login

# Deploy
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()
});

// Required: Export widget metadata
export const widgetMetadata: WidgetMetadata = {
  description: "Display weather information",
  props: propSchema, // Use 'props', not 'schema'!
};

// Required: Export default component
export default function WeatherDisplay() {
  const { props, isPending } = useWidget<z.infer<typeof propSchema>>();
  
  // Always handle loading state
  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

コンテンツセキュリティポリシー（CSP）

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

export const widgetMetadata: WidgetMetadata = {
  description: "Weather widget",
  props: z.object({ city: z.string() }),
  metadata: {
    csp: {
      // APIs to call
      connectDomains: ["https://api.weather.com"],
      // Static assets to load
      resourceDomains: ["https://cdn.weather.com"],
      // Iframes to embed
      frameDomains: ["https://embed.weather.com"],
      // Script directives
      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', // Required for widgets
});

// Register a dual-protocol widget
server.uiResource({
  type: "mcpApps", // Works with BOTH MCP Apps clients 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: `...`,
  // Unified metadata (dual-protocol)
  metadata: {
    csp: { connectDomains: ["https://api.example.com"] },
    prefersBorder: true,
  },
  // ChatGPT-specific overrides
  appsSdkMetadata: {
    "openai/widgetDescription": "ChatGPT-specific description",
    "openai/customFeature": "some-value", // Any custom OpenAI metadata
  },
});

プロジェクト構成

my-mcp-server/
├── resources/           # React widgets (apps-sdk)
│   └── widget.tsx
├── public/             # Static assets
├── index.ts            # Server entry point
├── 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", // Must exist in 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 - コンテンツセキュリティポリシー
• appsSdkMetadata - ChatGPT 固有のオーバーライド

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

• starter - 多機能（ツール、リソース、プロンプト、ウィジェット）
• mcp-apps - 製品例を含む ChatGPT 最適化版
• blank - 最小限のボイラープレート