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

# AI アシスタントを接続する（MCP）

> Claude、ChatGPT、Cursor、VS Code などの MCP クライアントを、ブラウザーでの認可または API キーで、Alforse の会社に接続します。

Alforse は Model Context Protocol（MCP）サーバーを提供しており、AI アシスタントが ERP のデータ（品目、販売、購買、生産、在庫、品質、会計など）を調べたり操作したりできます。社内の誰でも自分のアシスタントを接続でき、開発者はコーディング用クライアントやスクリプトを接続できます。アシスタントができるのは、接続に使った本人またはキーに許可されていることだけです。

## 必要なもの

| | 値 |
| - | - |
| サーバー URL | `https://app.alforse.com/api/mcp` |
| トランスポート | Streamable HTTP（`POST` のみ） |
| プラン | **ビジネス**（Business）。ほかのプランでは、サーバーはすべての呼び出しを拒否します（[制限](#limits)を参照）。 |
| サーバーマニフェスト | `https://app.alforse.com/.well-known/mcp.json`（公開。会社のデータは含まれません） |

アシスタントにサインインさせる方法は 2 つあります。お使いのクライアントが対応している方を選んでください。

| クライアント | 接続方法 |
| - | - |
| Claude.ai、Claude Desktop、ChatGPT | **ブラウザーでの認可（OAuth）。**キーの作成も貼り付けも不要です。 |
| Claude Code | どちらでも可。キーを省略すると初回の使用時にブラウザーでの認可が始まります。または API キーを渡します。 |
| Cursor、VS Code、Codex、スクリプト、CI | `Authorization` ヘッダーに **API キー** |
| ローカル（stdio）サーバーしか実行できないクライアント | `mcp-remote` 経由の API キー |

## ブラウザーでの認可で接続する

Alforse 側で事前に設定する必要はありません。アシスタントにサーバー URL を追加すると、Alforse が接続の承認を求めてきます。

**アシスタントにサーバーを追加します。**

* \*\*Claude Desktop / Claude.ai：\*\***Settings → Connectors → Add custom connector** を開き、`https://app.alforse.com/api/mcp` を貼り付けます。
* \*\*ChatGPT：\*\***Settings → Connectors → Add** を開き、同じ URL を貼り付けます。ChatGPT でカスタムコネクターを利用できるのは、一部のプランのみです。
* **Claude Code：**`claude mcp add --transport http alforse https://app.alforse.com/api/mcp`（`--header` は付けません）。

\*\*Alforse にサインインします。\*\*アシスタントがブラウザーで Alforse のページを開きます。求められた場合はサインインしてください。

**リクエストを確認します。****アプリケーションを認可**（Authorize Application）ページには、アシスタントの名前と戻り先のウェブサイトが表示され、続けて "is requesting access to your Alforse account."（があなたの Alforse アカウントへのアクセスを要求しています。）と表示されます。その下に、要求された**スコープ**（`mcp:tools`）が表示されます。

**会社を選びます。\*\*\*\*会社**で、アシスタントが作業する会社を選びます。所属する会社が 1 つだけの場合は、選択肢なしで表示されます。1 つの接続が機能するのは、ちょうど 1 つの会社です。別の会社で作業するには、もう一度接続して、その会社を選んでください。

\*\*認可を選択します。\*\*ブラウザーがアシスタントに戻り、接続が完了します。「直近の販売オーダー 5 件を一覧にして」など簡単な質問をして、確認してください。

NOTE

**認可できる人**

**アプリケーションを認可**ページを使うには、現在の会社で**設定**の**更新**権限が必要です。権限がないと、"Access Denied" と表示されてアプリに戻されます。管理者に権限を依頼するか、管理者があなたのために作成する [API キー](https://docs.alforse.com/ja/docs/building/api-keys.md)を使ってください。

### 接続でできること

* 接続は、**あなたとして、選んだ会社で**、現在の[権限](https://docs.alforse.com/ja/docs/reference/permissions.md)とまったく同じ範囲で動作します。権限が変わると、アシスタントの権限も一緒に変わります。
* その会社の有効なメンバーでなくなると、動作しなくなります。
* 会社とユーザーは常に接続そのものから決まります。アシスタントが引数を変えて、会社を切り替えたり別の人として動作したりすることはできません。

### サインインの裏側の仕組み

クライアントがこれを自動的に処理するため、ここでの詳細は、独自のクライアントを開発する人向けです。

| ステップ | エンドポイント |
| - | - |
| トークンのない呼び出しには `401` と `WWW-Authenticate: Bearer resource_metadata="https://app.alforse.com/.well-known/oauth-protected-resource"` が返されます | `/api/mcp` |
| 保護リソースのメタデータ | `https://app.alforse.com/.well-known/oauth-protected-resource` |
| 認可サーバーのメタデータ | `https://app.alforse.com/.well-known/oauth-authorization-server` |
| クライアント登録（オープンな動的登録。`client_name` と `redirect_uris` を含む JSON ボディ） | `https://app.alforse.com/register` |
| 承認ページ | `https://app.alforse.com/authorize` |
| トークン交換と更新 | `https://app.alforse.com/token` |

* グラントタイプ：`authorization_code` と `refresh_token`。レスポンスタイプ：`code`。
* `S256` の PKCE。パブリッククライアント（トークンエンドポイントの認証方式が `none`）は、コードチャレンジを送る必要があります。
* トークンエンドポイントでのクライアント認証：`client_secret_post` または `none`。
* スコープ：`mcp:tools`。
* 認可コードの有効期間は 10 分で、1 回だけ使えます。アクセストークンの有効期間は 1 時間（`expires_in: 3600`）で、クライアントがリフレッシュトークンで更新します。

## API キーで接続する

ブラウザーでのサインインを開けないクライアントや、スクリプトにはキーを使います。キーは管理者が**設定 → APIキー**で作成します。キーは固有の権限スコープを持ち、1 つの会社に属します。キーの作成とスコープの設定については、[API キー](https://docs.alforse.com/ja/docs/building/api-keys.md)を参照してください。

キーは `Authorization` ヘッダーで送ります。

```http theme={null}
Authorization: Bearer alf_your_key_here
```

`alforse-key: alf_your_key_here` ヘッダーも使用できます。

TIP

**コマンドは用意されています**

キーを作成すると、そのダイアログのキーの横に**MCPコマンド**が表示されます。これをコピーすると、Claude Code にサーバーを 1 ステップで追加できます。

### クライアントの設定

**Claude Code**

```bash theme={null}
claude mcp add --transport http alforse \
  https://app.alforse.com/api/mcp \
  --header "Authorization: Bearer alf_your_key_here"
```

**Cursor**（プロジェクトの `.cursor/mcp.json`、または既存の `mcpServers` にマージします）

```json theme={null}
{
  "mcpServers": {
    "alforse": {
      "url": "https://app.alforse.com/api/mcp",
      "headers": { "Authorization": "Bearer alf_your_key_here" }
    }
  }
}
```

**VS Code**（`.vscode/mcp.json`。VS Code がキーの入力を求めるため、キーはファイルに保存されません）

```json theme={null}
{
  "inputs": [
    { "id": "alforse-key", "type": "promptString", "description": "Alforse API key", "password": true }
  ],
  "servers": {
    "alforse": {
      "type": "http",
      "url": "https://app.alforse.com/api/mcp",
      "headers": { "Authorization": "Bearer ${input:alforse-key}" }
    }
  }
}
```

**その他のクライアント：**URL `https://app.alforse.com/api/mcp` と `Authorization: Bearer …` ヘッダーを渡します。URL の欄の名前はクライアントによって異なります（たとえば `url` や `serverUrl`）。お使いのクライアントのドキュメントを確認してください。

HEADS UP

**クライアントごとに 1 つのキー**

アシスタントやスクリプトごとに別のキーを使い、必要なスコープだけを付与してください（読み取り専用のアシスタントには View スコープのみ）。そうすれば、ほかに影響せずに、1 つのキーだけを取り消したり絞り込んだりできます。

## アシスタントに見えるツール

操作ごとに 1 つのツールを用意する代わりに、サーバーはすべての操作に到達できる 3 つのツールを提供します。

| ツール | 内容 |
| - | - |
| `search_tools` | 利用できる Alforse の操作を、キーワード、モジュール、リスク区分（`READ`、`WRITE`、`DESTRUCTIVE`）で検索します。既定では 20 件、最大 100 件を返します。 |
| `describe_tool` | 1 つまたは複数の操作の完全な仕様（説明、必要な権限、入力と応答のスキーマ）を返します。 |
| `call_tool` | 引数の JSON オブジェクトを渡して、操作を実行します。 |

操作は、次の領域に分かれています：account、accounting、documents、inventory、invoicing、items、people、production、purchasing、quality、resources、sales、settings、shared、users。利用できるのは、Alforse が明示的に公開した操作だけです。一部の操作は、意図的にサーバーに出していません。

* すべての呼び出しは、アプリと同じ権限チェックを通り、書き込みは同じサービス層で検証されます。
* 各操作にはリスク区分があるため、アシスタントは `WRITE` や `DESTRUCTIVE` の操作を実行する前に、確認を求めることができます。
* 一覧の読み取りは、既定で **25 行**を返します。アシスタントは `limit`（1～100）と `offset` でページを送ります。
* アシスタントには、会社のタイムゾーンでの今日の日付が伝えられるため、「先週」のような相対的な日付が正しく解決されます。

## 制限

| 制限 | 値 |
| - | - |
| プラン | ビジネス。それ以外では、すべての呼び出しが `402` を返します。 |
| ブラウザーで認可した接続 | **ユーザーごとに 1 分あたり 60 リクエスト**。そのユーザーのすべての接続で共有されます |
| API キー | キー自身の制限。既定では 1 分あたり 60 リクエスト（[詳細](https://docs.alforse.com/ja/docs/building/api-keys.md#rate-limit)） |
| アクセストークンの有効期間 | 1 時間。リフレッシュトークンで自動更新されます |
| 一覧の読み取り 1 回の行数 | 既定は 25 行、1 ページあたり最大 100 行 |

制限に達すると、サーバーは `429` を返し、`Retry-After` ヘッダーと、`X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` ヘッダーを付けます。`Retry-After` の秒数だけ待ってから再試行してください。

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

| 症状 | 原因 | 対処 |
| - | - | - |
| `402` と "The MCP server is available on the Business plan. Upgrade to connect an agent to Alforse."（MCP サーバーはビジネスプランで利用できます。エージェントを Alforse に接続するには、アップグレードしてください。） | 会社がビジネスプランではありません。 | プランをアップグレードしてください（[請求とサブスクリプション](https://docs.alforse.com/ja/docs/reference/billing.md)を参照）。接続自体は変更不要です。 |
| アシスタントが Alforse を開いた直後に "Access Denied" | 承認ページに必要な、**設定**の**更新**権限がありません。 | 管理者にその権限を依頼するか、API キーで接続してください。 |
| **認可**を選択すると "Invalid company"（`403`） | 選択した会社のメンバーではありません。 | 所属している会社を選んでください。 |
| "Invalid redirect URI" または "Invalid client" | クライアントが、登録していない戻り先アドレスを送った、または登録が不明です。 | アシスタントからサーバーを削除して、もう一度追加し、新しく登録し直してください。 |
| "PKCE required for public clients" | シークレットを持たないクライアントが、コードチャレンジを送りませんでした。 | PKCE（`S256`）に対応したクライアントを使ってください。 |
| 以前は動いていたのに、すべての呼び出しが `401` | アクセストークンの期限が切れて更新できなかった、その会社の有効なメンバーではなくなった、または API キーの期限切れや削除。 | 再接続（もう一度認可）するか、有効なキーを使ってください。 |
| `429` "Rate limit exceeded" | 1 分あたりの許容リクエスト数を超えました。 | `Retry-After` の時間だけ待ってください。アシスタントには、より少ない数の大きなページで取得するよう依頼してください。 |
| `405` "Method not allowed. Use POST." | URL をブラウザーで開いた、または `GET` で呼び出しました。 | 正常な動作です。MCP クライアントは `POST` を使います。代わりに、アシスタントに URL を追加してください。 |
| ツールの呼び出しが権限エラーで失敗する | 接続しているユーザー、またはキーのスコープで、その操作が許可されていません。 | Alforse で権限またはスコープを付与してください。次の呼び出しから反映されます。 |
| アシスタントが操作を見つけられない | その操作が MCP サーバーで公開されていない、または検索語が一致していません。 | アシスタントに、モジュール（たとえば "sales"）やフィールド名で検索するよう依頼してください。 |

## 関連ページ

**API キー**

コーディング用クライアント、スクリプト、CI 向けのキーを作成し、スコープを設定します。

[Open](https://docs.alforse.com/ja/docs/building/api-keys.md)

**権限とアクセス**

接続したアシスタントが読み取り、変更できる範囲です。

[Open](https://docs.alforse.com/ja/docs/reference/permissions.md)

**Slack のアシスタント**

Slack から Alforse を使います。

[Open](https://docs.alforse.com/ja/docs/integrations/assistant.md)

**請求とサブスクリプション**

ご利用のプランと、アップグレードの方法です。

[Open](https://docs.alforse.com/ja/docs/reference/billing.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.