> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shanone.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# セットアップ

> Cursor、Claude Code、Codexでemma MCP Serverを設定し、エージェントからemmaのツールとSkillを使い始めましょう。

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

## 前提条件

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

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

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

1. [emma](https://app.emma.ai)にログイン
2. **API Keys**に移動
3. **Create API Key**をクリックし、生成されたキー（`emma_sk_`で始まる）をコピー

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

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

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

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

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

<Tabs>
  <Tab title="Cursor">
    `~/.cursor/mcp.json`を編集（または**Cursor Settings → MCP**からサーバーを追加）：

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

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

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

    ```bash theme={null}
    claude mcp add --transport http emma \
      "https://app.emma.ai/api/v1/mcp" \
      --header "Authorization: Bearer YOUR_API_KEY"
    ```

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

    ```json theme={null}
    {
      "mcpServers": {
        "emma": {
          "type": "http",
          "url": "https://app.emma.ai/api/v1/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    `~/.codex/config.toml`を編集：

    ```toml theme={null}
    [mcp_servers.emma]
    url = "https://app.emma.ai/api/v1/mcp"
    http_headers = { Authorization = "Bearer YOUR_API_KEY" }
    ```
  </Tab>
</Tabs>

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

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

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

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

<Note>
  ローカルブリッジはnpmで[`@duzzle/emma-mcp`](https://www.npmjs.com/package/@duzzle/emma-mcp)として公開されており、Node.js 18以上が必要です。[emma MCP Server](/ja/mcp/emma-mcp-server)に記載されているのと同じツール群を提供します。
</Note>

## 接続の確認

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

1. クライアントのAIチャットを開く
2. 「emmaの接続状態を確認して」と入力
3. `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`環境変数が必須               |

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

### 接続の問題

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

  <Accordion title="401 Unauthorized / invalid_api_key">
    APIキーが未設定、形式が不正、または無効化されています。emmaダッシュボードの**API Keys**から新しいキーを生成し、設定を更新してください。
  </Accordion>

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

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

  <Accordion title="代わりにローカルstdioブリッジを使う場合">
    `npx -y @duzzle/emma-mcp`の起動に失敗する場合は、Node.js 18以上がインストールされていること、MCP設定の`env`ブロックに`EMMA_API_KEY`が設定されていることを確認してください。
  </Accordion>
</AccordionGroup>

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

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

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

  <Step title="定期的にキーをローテーション">
    emmaダッシュボードの**API Keys**から定期的に新しいAPI Keyを生成し、古いものを無効にしてください。
  </Step>
</Steps>

## 次のステップ

<CardGroup cols={2}>
  <Card title="emma MCP Server" icon="server" href="/ja/mcp/emma-mcp-server">
    利用可能なツールとユースケースについて学ぶ
  </Card>

  <Card title="ツールリファレンス" icon="book" href="/ja/mcp/tools-reference">
    全ツールの詳細ドキュメント
  </Card>
</CardGroup>