***

title: Client Integration
description: Step-by-step guide to installing Alephant MCP in Cursor and other hosts
------------------------------------------------------------------------------------

This document explains how to **import and configure** Alephant MCP in host environments such as **Cursor, Claude Desktop, and VS Code (MCP extension)**.

## 1. Quick Installation

This project is distributed via NPM and supports seamless integration using `npx`. You can also install it globally:

```bash
npm install -g @alephantai/mcp
```

## 2. Environment Variables

Before integrating into your client, gather the necessary environment variables based on your desired execution mode.

| Variable                  | Required               | Description                                                           |
| ------------------------- | ---------------------- | --------------------------------------------------------------------- |
| `ALEPHANT_API_BASE_URL`   | Yes                    | SaaS API base URL, e.g., `https://api.alephant.io`                    |
| `ALEPHANT_VIRTUAL_KEY`    | Yes (for VK mode)      | Virtual key; **read-only, scoped to the cockpit of that key**         |
| `ALEPHANT_PAT`            | Yes (for Manager mode) | Personal Access Token                                                 |
| `ALEPHANT_WORKSPACE_ID`   | Yes (for Manager mode) | Workspace UUID                                                        |
| `ALEPHANT_RATE_LIMIT_RPM` | No                     | Client-side HTTP call limit per minute, default `60`; `0` disables it |

## 3. Integration in Cursor

To enable the "Full-Stack Governance Cockpit" in Cursor:

1. Open **Cursor Settings** → **Features** → **MCP**
2. Click **+ Add New MCP Server**
3. Fill in the following information:
   * **Type**: `command`
   * **Command**: `npx`
   * **Args**: `-y` and `@alephantai/mcp` (in two separate fields)
4. In **Environment variables**, fill in the corresponding variables mentioned above (choose either the VK or Manager combination).
5. Save and ensure the status indicator turns **green**.

## 4. `mcp.json` Configuration Snippets

For host environments like Claude Desktop that use an `mcp.json` file, you can refer to the two most common configurations below:

### Virtual Key (VK) — Read-Only

```json
{
  "mcpServers": {
    "alephant": {
      "command": "npx",
      "args": ["-y", "@alephantai/mcp"],
      "env": {
        "ALEPHANT_API_BASE_URL": "https://api.alephant.ai",
        "ALEPHANT_VIRTUAL_KEY": "vk-your-key-here"
      }
    }
  }
}
```

### Manager — Full Management

```json
{
  "mcpServers": {
    "alephant-workspace": {
      "command": "npx",
      "args": ["-y", "@alephantai/mcp"],
      "env": {
        "ALEPHANT_API_BASE_URL": "https://api.alephant.ai",
        "ALEPHANT_PAT": "pat_your_token_here",
        "ALEPHANT_WORKSPACE_ID": "00000000-0000-0000-0000-000000000000"
      }
    }
  }
}
```

*Multi-Workspace Configuration:* Duplicate an `mcpServers` entry for each PAT/workspace and ensure the names are unique (e.g., `alephant-prod` and `alephant-staging`).

## 5. Local Development and Scheduled Tasks

**Local Development**:
Run `npx` from the parent directory of the `alephant-mcp` repository, or change the `command` in the configuration to `node` and point `args` to `./bin/alephant-mcp.js`.

**Scheduled Tasks and Proactive Reporting**:

* **AI Scheduling**: Simply tell the AI: *"Schedule a task: Run Alephant audit every Monday at 9 AM."*
* **Local Cron**: Add to your crontab: `0 9 * * 1 npx --yes --package=@alephantai/mcp alephant-mcp --audit >> ./AUDIT.md`