ローカルMCPで接続する

MCPクライアントがローカルstdioサーバーを起動する場合は、この手順を使います。クライアントがリモートMCPサーバーまたはカスタムコネクタに対応している場合は、まずリモートMCPを使うのがおすすめです。

事前準備

Amethyst MCPの実行にはNode.js 20以降が必要です。Node.jsをまだインストールしていない場合は、先にNode.js公式ダウンロードページからインストールしてください。

Amethyst MCPをダウンロードする

上記リンクから amethyst-mcp.tar.gz をダウンロードします。

ダウンロードしたら、利用するターミナルに合わせてファイルを展開します。

tar -xzf amethyst-mcp.tar.gz
cd amethyst-mcp
ls -l dist/index.js

tar -xzf .\amethyst-mcp.tar.gz
Set-Location .\amethyst-mcp
Get-Item .\dist\index.js

tar -xzf amethyst-mcp.tar.gz
cd amethyst-mcp
dir dist\index.js

配布物には依存関係も含まれています。Node.jsが利用できる環境であれば、OSごとに別のファイルを選ぶ必要はありません。展開後に npm install や pnpm install を実行する必要もありません。

パスを確認する

MCPクライアントには、Node.jsの絶対パスと、展開した dist/index.js の絶対パスを設定します。利用するターミナルに合わせて確認してください。

Node.jsのパスを確認します。

which node

展開したディレクトリで、Amethyst MCPのエントリーポイントを確認します。

echo "$(pwd)/dist/index.js"

Node.jsのパスを確認します。

(Get-Command node).Source

展開したディレクトリで、Amethyst MCPのエントリーポイントを確認します。

(Resolve-Path .\dist\index.js).Path

Node.jsのパスを確認します。

where node

展開したディレクトリで、Amethyst MCPのエントリーポイントを確認します。

for %I in (dist\index.js) do @echo %~fI

表示された絶対パスを、次の設定で使います。

MCPクライアントに設定する

設定方法はMCPクライアントによって異なります。具体的な設定場所や反映方法は、利用するクライアントの公式ドキュメントを確認してください。

Amethyst MCPをローカルstdioサーバーとして追加する場合は、次の値を使います。

{
  "mcpServers": {
    "amethyst": {
      "command": "<absolute-path-to-node>",
      "args": ["<absolute-path-to-amethyst-mcp>/dist/index.js"],
      "env": {
        "AMETHYST_GRAPHQL_ENDPOINT": "https://api.amethy.st/query",
        "AMETHYST_FRONTEND_URL": "https://app.amethy.st"
      }
    }
  }
}

AMETHYST_GRAPHQL_ENDPOINT を省略した場合、Amethyst MCP は https://api.amethy.st/query を使用します。設定内容を確認しやすくするため、明示しておくことをおすすめします。

Codexに設定する場合

Codexでは、~/.codex/config.toml に次の設定を追加します。既存の [mcp_servers.*] がある場合は消さずに、amethyst のブロックだけ追加します。

[mcp_servers.amethyst]
command = "<absolute-path-to-node>"
args = ["<absolute-path-to-amethyst-mcp>/dist/index.js"]

  [mcp_servers.amethyst.env]
  AMETHYST_GRAPHQL_ENDPOINT = "https://api.amethy.st/query"
  AMETHYST_FRONTEND_URL = "https://app.amethy.st"

MCP client機能を有効化していないCodex環境では、同じ config.toml に次の設定も追加します。既に [features] がある場合は、その中に rmcp_client = true を追加してください。

[features]
rmcp_client = true

設定を変更したらCodexを再起動します。

MCPクライアントを再起動する

設定を変更したら、MCPクライアントを完全に終了してから再起動します。多くのクライアントでは、MCPサーバー設定はアプリ起動時に読み込まれます。

OAuth認可を完了する

再起動後、MCPクライアントでAmethystのツールを呼び出します。

アクセスできるAmethystのワークスペースを一覧して

初回のツール呼び出し時は、次の流れになります。

ブラウザでAmethystが開く
必要に応じてAmethystにログインする
許可するワークスペースを選ぶ
Approveする
一時的なローカルホストコールバックページに戻る

認可が完了したらMCPクライアントに戻ります。自動で完了しない場合は、同じ依頼をもう一度実行してください。

認可をやり直す

再認可したい場合は、保存済みクレデンシャルを削除してMCPクライアントを再起動します。

macOS / Linux: ~/.config/amethyst-mcp/oauth-token.json
Windows: %APPDATA%\amethyst-mcp\oauth-token.json

次回のAmethystツール呼び出し時に、OAuth認可が再度始まります。

トラブルシュート

MCPクライアントがサーバーを起動できない場合は、command と args の絶対パスを確認してください。
ブラウザが開かない場合は、MCPクライアントのエラー出力に表示される認可URLを手動で開いてください。
401 または 403 エラーが出る場合は、保存済みクレデンシャルを削除し、MCPクライアントを再起動して再認可してください。
ダウンロードリンクを開けない場合は、Amethystサポートにお問い合わせください。