> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Installation

> Install and configure the ZeroPath MCP Server for your AI tool

## Installation

<Tabs>
  <Tab title="Quick Install (pip)">
    Install directly from GitHub using pip:

    ```bash theme={null}
    pip install git+https://github.com/ZeroPathAI/zeropath-mcp-server.git
    ```

    Pin to a specific version:

    ```bash theme={null}
    pip install git+https://github.com/ZeroPathAI/zeropath-mcp-server.git@v0.1.0
    ```
  </Tab>

  <Tab title="uvx (no install)">
    Run without installing using uvx:

    ```bash theme={null}
    uvx --from git+https://github.com/ZeroPathAI/zeropath-mcp-server zeropath-mcp-server
    ```

    Pin to main branch:

    ```bash theme={null}
    uvx --from "git+https://github.com/ZeroPathAI/zeropath-mcp-server@main" zeropath-mcp-server
    ```
  </Tab>

  <Tab title="From Source">
    Clone and install with uv:

    ```bash theme={null}
    git clone https://github.com/ZeroPathAI/zeropath-mcp-server.git
    cd zeropath-mcp-server
    uv sync
    ```
  </Tab>

  <Tab title="PyPI">
    ```bash theme={null}
    pip install zeropath-mcp-server
    ```
  </Tab>
</Tabs>

<Warning>
  Python **3.12+** is required. Check your version with `python3 --version`.
</Warning>

## Setup

<Steps>
  <Step title="Generate API Key">
    Create a user-scoped or admin API key from [ZeroPath Settings](https://zeropath.com/app/settings/api). You need the **Token ID** and **Token Secret**.
  </Step>

  <Step title="Set Environment Variables">
    ```bash theme={null}
    export ZEROPATH_TOKEN_ID=your_token_id
    export ZEROPATH_TOKEN_SECRET=your_token_secret
    export ZEROPATH_ORG_ID=your_org_id
    export ZEROPATH_BASE_URL="https://zeropath.com"  # optional, defaults to https://zeropath.com
    ```

    <Note>
      Set `ZEROPATH_BASE_URL` to target a different environment, e.g. `https://your-instance.example.com`
    </Note>
  </Step>

  <Step title="Configure Your MCP Client">
    Add the ZeroPath MCP server to your AI tool's config file. See the client configuration section below.
  </Step>
</Steps>

## Client Configuration

<Tabs>
  <Tab title="Claude Desktop / Cursor (uvx)">
    For **Claude Desktop**, edit your config file:

    * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

    For **Cursor**, add to MCP settings (Settings → MCP).

    ```json theme={null}
    {
      "mcpServers": {
        "zeropath": {
          "command": "uvx",
          "args": [
            "--from",
            "git+https://github.com/ZeroPathAI/zeropath-mcp-server",
            "zeropath-mcp-server"
          ],
          "env": {
            "ZEROPATH_BASE_URL": "https://zeropath.com",
            "ZEROPATH_TOKEN_ID": "your_token_id",
            "ZEROPATH_TOKEN_SECRET": "your_token_secret",
            "ZEROPATH_ORG_ID": "your_org_id"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="From Source">
    If you installed from source, point to the local project:

    ```json theme={null}
    {
      "mcpServers": {
        "zeropath": {
          "command": "uv",
          "args": [
            "run",
            "--project",
            "/path/to/zeropath-mcp-server",
            "python",
            "-m",
            "zeropath_mcp_server"
          ],
          "env": {
            "ZEROPATH_BASE_URL": "https://zeropath.com",
            "ZEROPATH_TOKEN_ID": "your_token_id",
            "ZEROPATH_TOKEN_SECRET": "your_token_secret",
            "ZEROPATH_ORG_ID": "your_org_id"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="'Unknown tool' error">
    The MCP server may not have started or failed to fetch the manifest. Check your terminal for startup errors. Ensure the server process is running and can reach `https://zeropath.com/mcp-manifest.json`.
  </Accordion>

  <Accordion title="Authentication failed">
    Verify `ZEROPATH_TOKEN_ID` and `ZEROPATH_TOKEN_SECRET` are correct and the API key is active. You can test by visiting [ZeroPath Settings](https://zeropath.com/app/settings/api) to confirm the key status.
  </Accordion>

  <Accordion title="Organization not found">
    Confirm `ZEROPATH_ORG_ID` matches an organization you have access to. You can find your org ID in [ZeroPath Settings](https://zeropath.com/app/settings).
  </Accordion>

  <Accordion title="'organizationId is required' error">
    Pass `organizationId` explicitly in the tool input, or set `ZEROPATH_ORG_ID` in your environment. The server auto-injects the org ID when the environment variable is configured.
  </Accordion>

  <Accordion title="Schema validation failed">
    Check the error details — the server validates all inputs before calling ZeroPath's API. Common causes: wrong field names (e.g., `status` instead of `issueStatus`), wrong types (e.g., string instead of number for severity).
  </Accordion>
</AccordionGroup>

### General Tips

* Restart your AI client after changing MCP configuration.
* Ensure Python 3.12+ is in your `PATH`.
* Use `uvx` for the simplest setup — no installation required.
* Check the [GitHub repo](https://github.com/ZeroPathAI/zeropath-mcp-server) for updates and known issues.