Amethyst MCP

Amethyst MCP lets an AI client use Amethyst tools through the Model Context Protocol.

Amethyst MCP is provided for users with an active Amethyst contract. It is not a general public download.

What you can do

With Amethyst MCP, a connected AI client can call Amethyst tools for tasks such as checking available workspaces, listing projects, and using supported Search Analytics, User Analytics, and Index Worker operations.

You do not need to copy an Amethyst token from browser developer tools. On the first tool call, Amethyst MCP opens Amethyst in your browser, asks you to approve access, and saves a local credential for later use.

Prerequisite

Amethyst MCP requires Node.js 20 or later. If Node.js is not already available on your machine, install it first from the official Node.js download page.

Download Amethyst MCP

Download amethyst-mcp.tar.gz from the link above.

After downloading the file, extract it using the tab for your terminal.

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

The package is already bundled and works across supported operating systems as long as Node.js is available. You do not need to run npm install or pnpm install after extracting it.

Prepare the paths

The MCP client needs the absolute path to Node.js and the absolute path to the extracted dist/index.js. Use the tab for your terminal.

Check the Node.js path:

which node

From the extracted directory, check the Amethyst MCP entrypoint path:

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

Check the Node.js path:

(Get-Command node).Source

From the extracted directory, check the Amethyst MCP entrypoint path:

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

Check the Node.js path:

where node

From the extracted directory, check the Amethyst MCP entrypoint path:

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

Use the full paths returned by these commands in the client configuration.

Configure your MCP client

Configuration steps vary by MCP client. Use the official documentation for the client you use.

Use the following values when adding Amethyst MCP as a local stdio server.

{
  "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"
      }
    }
  }
}

If AMETHYST_GRAPHQL_ENDPOINT is omitted, Amethyst MCP uses https://api.amethy.st/query. Keep the setting explicit when you want the configuration to be easy to review.

Configure Codex

For Codex, add the following settings to ~/.codex/config.toml. If the file already has other [mcp_servers.*] entries, keep them and add only the amethyst block.

[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"

If MCP client support is not enabled in your Codex environment, also add the following setting to the same config.toml. If [features] already exists, add rmcp_client = true inside the existing table.

[features]
rmcp_client = true

Restart Codex after editing the configuration.

Restart the MCP client

Fully quit and reopen your MCP client after editing the configuration. Many clients load MCP server settings only when the app starts.

Complete OAuth authorization

After restarting, ask your MCP client to use an Amethyst tool, for example:

List the Amethyst workspaces I can access.

On the first tool call:

Your browser opens Amethyst.
Sign in to Amethyst if prompted.
Select the workspaces you want to allow.
Approve the request.
The browser returns to a temporary localhost callback page.

After authorization succeeds, return to your MCP client and run the same request again if it did not complete automatically.

Reset authorization

If you need to authorize again, delete the saved credential and restart the MCP client.

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

The next Amethyst tool call will start the OAuth flow again.

Troubleshooting

If your MCP client cannot start the server, recheck the command path and the args path.
If the browser does not open, check the MCP client error output for the authorization URL and open it manually.
If you see a 401 or 403 error, delete the saved credential, restart the MCP client, and authorize again.
If the download link cannot be opened, contact Amethyst support.