Skip to main content

Set Up MCP Server with Claude Code

This guide covers how to set up the Palette MCP server with Claude Code. You can install the server through the Palette Agent Toolkit plugin, which bundles the MCP server configuration and four diagnostic skills in a single install, or configure the server manually as a container. We recommend the plugin install for most Claude Code users.

Prerequisites​

  • Claude Code installed on your workstation. Refer to the Claude Quickstart page for more information.

  • A Palette account.

  • A Palette API key. Refer to the Create API Key guide for more information.

  • If you plan to configure the MCP server manually, a container engine, such as Docker or Podman.

Set Up with the Palette Agent Toolkit Plugin​

The Palette Agent Toolkit plugin bundles the MCP server configuration and four diagnostic skills (diagnose-cluster, diagnose-edge, health-overview, and access-review).

  1. Start Claude Code in a terminal. Ensure that you authenticate with Claude by following the prompts.

    claude

  2. Add the Palette Agent Toolkit marketplace.

    /plugin marketplace add spectrocloud/palette-agent-toolkit

  3. Install the Palette plugin from the marketplace.

    /plugin install palette@palette-agent-toolkit

  4. Configure your Palette connection. Open the plugin menu, select the palette plugin, and choose Configure options.

    /plugin

    Set the following options.

    OptionNotes
    Palette hostRequired. Your tenant URL, for example example.spectrocloud.com.
    Palette API keyRequired unless you use an auth token. Create one under User Menu > My API Keys.
    Palette auth tokenJWT alternative to an API key. Provide an API key or an auth token, not both.
    Custom CA file pathOptional. Path to a CA bundle for a self-hosted Palette behind a private CA.

    You must set the Palette host and either the Palette API key or the Palette auth token. Claude Code stores the API key and auth token in your operating system credential store, such as the macOS Keychain, Windows Credential Manager, or Linux Secret Service. Where no credential store is available, Claude Code falls back to ~/.claude/.credentials.json with 0600 permissions. You do not need to export shell variables or create a .env file.

    To provision the plugin without prompts, such as in a CI pipeline, pass the options as repeatable --config flags at install time instead. Replace the placeholders with your own values.

    claude plugin install palette@palette-agent-toolkit \
      --config host=<palette-api-endpoint> --config api_key=<palette-api-key>

  5. Verify the plugin is active and the MCP server is connected.

    claude mcp list

You can now use the Palette MCP server with Claude Code.

Set Up Manually​

Use this path if you prefer to configure the container image directly instead of installing the plugin.

  1. Open a terminal session on your local machine.

  2. (Optional) To save the secrets you need to configure the Palette MCP server in a file rather than pass them directly as variables, create an .env-mcp file. The file approach is more secure and manageable.

    1. Issue the following command to create the .env-mcp file in your home directory under the .palette folder.

      mkdir -p ~/.palette
      touch ~/.palette/.env-mcp

    2. Populate the .env-mcp file with the following required values. Refer to the Server Configuration section for further details on the MCP server configuration values.

      cat << EOF > ~/.palette/.env-mcp
      PALETTE_HOST=<palette-api-endpoint>
      PALETTE_API_KEY=<palette-api-key>
      EOF
      chmod 600 ~/.palette/.env-mcp
      info

      By default, the server operates at the tenant scope. Every call sees results across every project that your credentials can access. To scope a request to a single project, mention the project by name or UID in your prompt instead of setting an environment variable; the assistant passes it as that call's project_uid argument.

  3. Issue the following command to create a folder to store kubeconfig files.

    Replace <local-path> with any folder on your machine.

    mkdir -p /<local-path>/kubeconfig

  1. Execute the following command to add the Palette MCP server to Claude Code, replacing the placeholders with your values. Ensure that you provide full filepaths for the kubeconfig folder and .env-mcp file, if you have configured one.

    If you want to use Podman, replace the command docker with podman.

    claude mcp add --transport stdio palette -- \
     docker run --rm -i --pull always \
     --mount type=bind,source=/<local-path>/kubeconfig,target=/tmp/kubeconfig \
     --env-file /<local-path>/.palette/.env-mcp \
     public.ecr.aws/palette-ai/palette-mcp-server:latest
    info

    To enable write tools, such as create, update, and delete, append --allow-write after the image name. By default, the server starts in read-only mode.

    warning

    The Palette MCP server automatically removes the kubeconfig files from the mounted /tmp/kubeconfig folder when the container stops.

    A kubeconfig contains cluster credentials. When you retrieve one with read_cluster_kubeconfig, pass write_path (requires --allow-write) to have the server save it locally with 0600 permissions, and treat the saved file as sensitive.

  2. Issue the following command to ensure that the MCP server was set up successfully.

    claude mcp list
    Example Output
    palette: docker run --rm -i --pull always --mount type=bind,source=/Users/test-user/kubeconfig,target=/tmp/kubeconfig
    --env-file /Users/test-user/.palette/.env-mcp public.ecr.aws/palette-ai/palette-mcp-server:latest - ✓ Connected

  3. Start Claude Code. Ensure that you authenticate with Claude by following the prompts.

    claude

  4. We recommend adding an Agent Skill to enable Claude to use kubeconfig files retrieved with read_cluster_kubeconfig to access clusters.

    Issue the following command to create the CLAUDE.md file on your machine if it does not exist.

    touch ~/.claude/CLAUDE.md

    Open the file in your preferred editor and paste the following snippet into it. Replace the <local-path> placeholder with a directory where you want to store kubeconfig files.

    # Palette MCP Server

    The Palette MCP server is a tool that you can use to interact with the Palette platform and its API. The MCP server is active as a container or a native binary and is accessible via the MCP protocol. A few things to keep in mind:

    - When you retrieve a cluster kubeconfig with the `read_cluster_kubeconfig` tool, save the file to a local directory on your machine located at `<local-path>/kubeconfig`. 

      Set the KUBECONFIG environment variable to the local filesystem path or use the `kubectl` command with the `--kubeconfig` flag, but ensure the path is correct.

You can now use the Palette MCP server with Claude Code.

Validation​

  1. Start Claude Code in a terminal. Ensure that you authenticate with Claude by following the prompts.

    claude
    Example Output
    Welcome to Claude Code

    ›

  2. Send a query about your Palette environment to check if your MCP server is connected to Palette.

    For example, you can ask "How many clusters do I have in Palette?" to learn more about your Palette clusters.

    Example Output
    ⏺ palette - read_clusters (MCP)(filters: { states: ["Running"] })

    ⏺ You have 1 active cluster in Palette.

    ┌──────────────────┬───────┬─────────┬─────────┬──────────────┐
    │       Name       │ Cloud │  State  │ Health  │   Location   │
    ├──────────────────┼───────┼─────────┼─────────┼──────────────┤
    │ aws-cluster-test │ AWS   │ Running │ Healthy │ Virginia, US │
    └──────────────────┴───────┴─────────┴─────────┴──────────────┘

    It was created on 2026-03-17 and is owned by test-user. It has 2 machine pools (1 control plane node + 1 worker node).

Next Steps​

Refer to the Palette MCP Server Operations page for further examples on how to leverage the functionality of the MCP server.