必要なもの
アシスタントにサインインさせる方法は 2 つあります。お使いのクライアントが対応している方を選んでください。
ブラウザーでの認可で接続する
Alforse 側で事前に設定する必要はありません。アシスタントにサーバー URL を追加すると、Alforse が接続の承認を求めてきます。接続でできること
- 接続は、あなたとして、選んだ会社で、現在の権限とまったく同じ範囲で動作します。権限が変わると、アシスタントの権限も一緒に変わります。
- その会社の有効なメンバーでなくなると、動作しなくなります。
- 会社とユーザーは常に接続そのものから決まります。アシスタントが引数を変えて、会社を切り替えたり別の人として動作したりすることはできません。
サインインの裏側の仕組み
クライアントがこれを自動的に処理するため、ここでの詳細は、独自のクライアントを開発する人向けです。- グラントタイプ：
authorization_codeとrefresh_token。レスポンスタイプ：code。 S256の PKCE。パブリッククライアント（トークンエンドポイントの認証方式がnone）は、コードチャレンジを送る必要があります。- トークンエンドポイントでのクライアント認証：
client_secret_postまたはnone。 - スコープ：
mcp:tools。 - 認可コードの有効期間は 10 分で、1 回だけ使えます。アクセストークンの有効期間は 1 時間（
expires_in: 3600）で、クライアントがリフレッシュトークンで更新します。
API キーで接続する
ブラウザーでのサインインを開けないクライアントや、スクリプトにはキーを使います。キーは管理者が設定 → APIキーで作成します。キーは固有の権限スコープを持ち、1 つの会社に属します。キーの作成とスコープの設定については、API キーを参照してください。 キーはAuthorization ヘッダーで送ります。
alforse-key: alf_your_key_here ヘッダーも使用できます。
クライアントの設定
.cursor/mcp.json、または既存の mcpServers にマージします）
.vscode/mcp.json。VS Code がキーの入力を求めるため、キーはファイルに保存されません）
https://app.alforse.com/api/mcp と Authorization: Bearer … ヘッダーを渡します。URL の欄の名前はクライアントによって異なります（たとえば url や serverUrl）。お使いのクライアントのドキュメントを確認してください。
アシスタントに見えるツール
操作ごとに 1 つのツールを用意する代わりに、サーバーはすべての操作に到達できる 3 つのツールを提供します。
操作は、次の領域に分かれています：account、accounting、documents、inventory、invoicing、items、people、production、purchasing、quality、resources、sales、settings、shared、users。利用できるのは、Alforse が明示的に公開した操作だけです。一部の操作は、意図的にサーバーに出していません。
- すべての呼び出しは、アプリと同じ権限チェックを通り、書き込みは同じサービス層で検証されます。
- 各操作にはリスク区分があるため、アシスタントは
WRITEやDESTRUCTIVEの操作を実行する前に、確認を求めることができます。 - 一覧の読み取りは、既定で 25 行を返します。アシスタントは
limit（1～100）とoffsetでページを送ります。 - アシスタントには、会社のタイムゾーンでの今日の日付が伝えられるため、「先週」のような相対的な日付が正しく解決されます。
制限
制限に達すると、サーバーは
429 を返し、Retry-After ヘッダーと、X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset ヘッダーを付けます。Retry-After の秒数だけ待ってから再試行してください。