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

# Instalação do MCP

> Instale e configure o Servidor MCP da ZeroPath para sua ferramenta de IA

<h2 id="installation">
  Instalação
</h2>

<Tabs>
  <Tab title="Instalação Rápida (pip)">
    Instale diretamente do GitHub usando pip:

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

    Fixe uma versão específica:

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

  <Tab title="uvx (sem instalação)">
    Execute sem instalar usando uvx:

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

    Fixe na branch main:

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

  <Tab title="A Partir do Código-Fonte">
    Clone e instale com 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+** é obrigatório. Verifique sua versão com `python3 --version`.
</Warning>

<h2 id="setup">
  Configuração Inicial
</h2>

<Steps>
  <Step title="Gerar uma chave de API">
    Crie uma chave de API com escopo de usuário ou de administrador em [ZeroPath Settings](https://zeropath.com/app/settings/api). Você precisa do **Token ID** e do **Token Secret**.
  </Step>

  <Step title="Definir as variáveis de ambiente">
    ```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>
      Defina `ZEROPATH_BASE_URL` para apontar para outro ambiente, por exemplo `https://your-instance.example.com`
    </Note>
  </Step>

  <Step title="Configurar seu cliente MCP">
    Adicione o servidor MCP da ZeroPath ao arquivo de configuração da sua ferramenta de IA. Consulte a seção de configuração de clientes abaixo.
  </Step>
</Steps>

<h2 id="client-configuration">
  Configuração do Cliente
</h2>

<Tabs>
  <Tab title="Claude Desktop / Cursor (uvx)">
    Para o **Claude Desktop**, edite seu arquivo de configuração:

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

    Para o **Cursor**, adicione nas configurações de MCP (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="A Partir do Código-Fonte">
    Se você instalou a partir do código-fonte, aponte para o projeto local:

    ```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>

<h2 id="troubleshooting">
  Solução de Problemas
</h2>

<AccordionGroup>
  <Accordion title="Erro 'Unknown tool'">
    O servidor MCP pode não ter iniciado ou pode ter falhado ao buscar o manifesto. Verifique erros de inicialização no seu terminal. Certifique-se de que o processo do servidor está em execução e consegue acessar `https://zeropath.com/mcp-manifest.json`.
  </Accordion>

  <Accordion title="Falha de autenticação">
    Verifique se `ZEROPATH_TOKEN_ID` e `ZEROPATH_TOKEN_SECRET` estão corretos e se a chave de API está ativa. Você pode testar visitando [ZeroPath Settings](https://zeropath.com/app/settings/api) para confirmar o status da chave.
  </Accordion>

  <Accordion title="Organização não encontrada">
    Confirme se `ZEROPATH_ORG_ID` corresponde a uma organização à qual você tem acesso. Você pode encontrar o ID da sua organização em [ZeroPath Settings](https://zeropath.com/app/settings).
  </Accordion>

  <Accordion title="Erro 'organizationId is required'">
    Passe `organizationId` explicitamente na entrada da ferramenta, ou defina `ZEROPATH_ORG_ID` no seu ambiente. O servidor injeta automaticamente o ID da organização quando a variável de ambiente está configurada.
  </Accordion>

  <Accordion title="Falha na validação do schema">
    Verifique os detalhes do erro — o servidor valida todas as entradas antes de chamar a API da ZeroPath. Causas comuns: nomes de campos incorretos (por exemplo, `status` em vez de `issueStatus`), tipos incorretos (por exemplo, string em vez de número para severidade).
  </Accordion>
</AccordionGroup>

<h3 id="general-tips">
  Dicas Gerais
</h3>

* Reinicie seu cliente de IA após alterar a configuração do MCP.
* Certifique-se de que o Python 3.12+ está no seu `PATH`.
* Use `uvx` para a configuração mais simples — não requer instalação.
* Confira o [repositório no GitHub](https://github.com/ZeroPathAI/zeropath-mcp-server) para atualizações e problemas conhecidos.