セットアップ

このガイドでは、emmaがホストするリモートサーバーであるemma MCP Serverへの接続方法を説明します。ローカルにインストールするパッケージはありません。

前提条件

始める前に、以下を確認してください：

対応クライアントのいずれか：Cursor、Claude Code、Codex
emmaアカウント
emma API Key（emmaダッシュボードのAPI Keysから作成）

ステップ1: API Keyを取得

emmaにログイン
API Keysに移動
Create API Keyをクリックし、生成されたキー（emma_sk_で始まる）をコピー

API Keyはパスワードと同様に扱ってください。バージョン管理にコミットしたり、公開したりしないでください。

ステップ2: クライアントを設定

emmaはMCPサーバーを以下のURLでStreamable HTTP経由で公開しています：

https://app.emma.ai/api/v1/mcp

APIキーはBearerトークンとして送信します：Authorization: Bearer YOUR_API_KEY。

Cursor
Claude Code
Codex

~/.cursor/mcp.jsonを編集（またはCursor Settings → MCPからサーバーを追加）：

{
  "mcpServers": {
    "emma": {
      "url": "https://app.emma.ai/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

設定後、Cursorを再起動してMCPサーバーを読み込みます。

Claude CodeはCLIから直接リモートHTTP MCPサーバーを追加できます：

claude mcp add --transport http emma \
  "https://app.emma.ai/api/v1/mcp" \
  --header "Authorization: Bearer YOUR_API_KEY"

またはプロジェクトの.mcp.jsonを直接編集：

{
  "mcpServers": {
    "emma": {
      "type": "http",
      "url": "https://app.emma.ai/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

~/.codex/config.tomlを編集：

[mcp_servers.emma]
url = "https://app.emma.ai/api/v1/mcp"
http_headers = { Authorization = "Bearer YOUR_API_KEY" }

上記のすべての例でYOUR_API_KEYを実際のemma API Keyに置き換えてください。

代替方法: ローカルstdioブリッジ

MCPクライアントがstdioトランスポートのみに対応している場合（またはまだカスタムHTTPヘッダーに対応していない場合）は、代わりにemmaのローカルNode.jsブリッジを使用してください。同じツール群を、同じバックエンドに、APIキー経由でプロキシします。

{
  "mcpServers": {
    "emma": {
      "command": "npx",
      "args": ["-y", "@duzzle/emma-mcp"],
      "env": {
        "EMMA_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

ローカルブリッジはnpmで@duzzle/emma-mcpとして公開されており、Node.js 18以上が必要です。emma MCP Serverに記載されているのと同じツール群を提供します。

接続の確認

emma MCP Serverが正しく動作しているか確認するには、ヘルスチェックツールを使用します：

クライアントのAIチャットを開く
「emmaの接続状態を確認して」と入力
emma_health_checkツールが、接続が正常でAPIキーが有効であることを報告するはずです

設定リファレンス

設定項目	値
リモートMCP URL	`https://app.emma.ai/api/v1/mcp`
トランスポート	Streamable HTTP
認証ヘッダー	`Authorization: Bearer <api_key>`（`X-API-Key: <api_key>`も可）
ローカルブリッジパッケージ	`@duzzle/emma-mcp`（npm）、`EMMA_API_KEY`環境変数が必須

トラブルシューティング

接続の問題

401 Unauthorized / api_key_required

リクエストにAPIキーが含まれていません。クライアント設定に上記の通りAuthorization: Bearer YOUR_API_KEYヘッダー（またはX-API-Key）が含まれているか確認してください。

401 Unauthorized / invalid_api_key

APIキーが未設定、形式が不正、または無効化されています。emmaダッシュボードのAPI Keysから新しいキーを生成し、設定を更新してください。

429 Rate Limited

APIキーのリクエストレート制限を超えています。しばらく待ってから再試行してください — レスポンスにはRetry-Afterヘッダーが含まれます。

ツールが表示されない

MCP設定を編集した後、クライアントを完全に再起動
設定ファイルのJSON/TOML構文エラーを確認
サーバー名がクライアントが期待する名前と一致していることを確認（通常はemma）
URLにタイプミスがないことを確認：https://app.emma.ai/api/v1/mcp

代わりにローカルstdioブリッジを使う場合

npx -y @duzzle/emma-mcpの起動に失敗する場合は、Node.js 18以上がインストールされていること、MCP設定のenvブロックにEMMA_API_KEYが設定されていることを確認してください。

セキュリティのベストプラクティス

環境変数を使用

クライアントが対応している場合は、コミットする設定ファイルにキーを直書きする代わりに環境変数を参照してください。

キーに用途がわかる名前を付ける

マシン/エージェントごとにわかりやすい名前でAPIキーを発行し、他のキーに影響を与えずに個別に無効化できるようにしてください。

定期的にキーをローテーション

emmaダッシュボードのAPI Keysから定期的に新しいAPI Keyを生成し、古いものを無効にしてください。

MCP

前提条件

ステップ1: API Keyを取得

ステップ2: クライアントを設定

代替方法: ローカルstdioブリッジ

接続の確認

設定リファレンス

トラブルシューティング

接続の問題

セキュリティのベストプラクティス

次のステップ

emma MCP Server

ツールリファレンス

​前提条件

​ステップ1: API Keyを取得

​ステップ2: クライアントを設定

​代替方法: ローカルstdioブリッジ

​接続の確認

​設定リファレンス

​トラブルシューティング

​接続の問題

​セキュリティのベストプラクティス

​次のステップ

emma MCP Server

ツールリファレンス

前提条件

ステップ1: API Keyを取得

ステップ2: クライアントを設定

代替方法: ローカルstdioブリッジ

接続の確認

設定リファレンス

トラブルシューティング

接続の問題

セキュリティのベストプラクティス

次のステップ