# Amethyst MCP

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

This package is already bundled. You do not need to run `npm install` or `pnpm install` after extracting it.

## Files

- `dist/index.js`: MCP server entrypoint.
- `README.md`: This setup guide.

## Prepare the paths

The MCP client needs the absolute path to Node.js and the absolute path to `dist/index.js`.

Check the Node.js path:

```bash
which node
```

Check the Amethyst MCP entrypoint path from this directory:

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

## Configure your MCP client

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

- Claude Desktop: https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop
- Claude Code: https://docs.claude.com/en/docs/claude-code/mcp
- Cursor: https://docs.cursor.com/advanced/model-context-protocol
- MCP client examples: https://modelcontextprotocol.io/clients

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

```json
{
  "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.

## 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 authorization

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

```text
List the Amethyst workspaces I can access.
```

On the first tool call:

1. Your browser opens Amethyst.
2. Sign in to Amethyst if prompted.
3. Select the workspaces you want to allow.
4. Approve the request.
5. 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 authorization 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.
