MCP

Client Integration

View as Markdown

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:

$npm install -g @alephantai/mcp

2. Environment Variables

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

VariableRequiredDescription
ALEPHANT_API_BASE_URLYesSaaS API base URL, e.g., https://api.alephant.io
ALEPHANT_VIRTUAL_KEYYes (for VK mode)Virtual key; read-only, scoped to the cockpit of that key
ALEPHANT_PATYes (for Manager mode)Personal Access Token
ALEPHANT_WORKSPACE_IDYes (for Manager mode)Workspace UUID
ALEPHANT_RATE_LIMIT_RPMNoClient-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

1{
2  "mcpServers": {
3    "alephant": {
4      "command": "npx",
5      "args": ["-y", "@alephantai/mcp"],
6      "env": {
7        "ALEPHANT_API_BASE_URL": "https://api.alephant.ai",
8        "ALEPHANT_VIRTUAL_KEY": "vk-your-key-here"
9      }
10    }
11  }
12}

Manager — Full Management

1{
2  "mcpServers": {
3    "alephant-workspace": {
4      "command": "npx",
5      "args": ["-y", "@alephantai/mcp"],
6      "env": {
7        "ALEPHANT_API_BASE_URL": "https://api.alephant.ai",
8        "ALEPHANT_PAT": "pat_your_token_here",
9        "ALEPHANT_WORKSPACE_ID": "00000000-0000-0000-0000-000000000000"
10      }
11    }
12  }
13}

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