> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/mcp-service/configuration-modes/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# Configuration & Execution

> Configure Alephant MCP credentials, execution modes, throttling, and audit runs

Alephant MCP is configured entirely through environment variables. The server validates credentials during startup and exits on invalid configuration.

## Required Base URL

| Variable                | Required | Description                                                                                        |
| ----------------------- | -------- | -------------------------------------------------------------------------------------------------- |
| `ALEPHANT_API_BASE_URL` | Yes      | SaaS API base URL, for example `https://alephant.io`. A trailing slash is accepted and normalized. |

## Permission Modes

| Mode                 | Required variables                       | Permissions                                 | Tool count |
| -------------------- | ---------------------------------------- | ------------------------------------------- | ---------- |
| **Virtual Key (VK)** | `ALEPHANT_VIRTUAL_KEY`                   | Read-only cockpit scope for one virtual key | 8          |
| **Manager**          | `ALEPHANT_PAT` + `ALEPHANT_WORKSPACE_ID` | Workspace-wide read/write access            | 27         |

Manager mode takes precedence whenever `ALEPHANT_PAT` is non-empty. If `ALEPHANT_PAT` is set without `ALEPHANT_WORKSPACE_ID`, startup fails. If neither `ALEPHANT_VIRTUAL_KEY` nor `ALEPHANT_PAT` is set, startup fails.

## VK Mode

Use VK mode for individual developers, agents, or automation that should only inspect usage and budget for one virtual key.

```bash
ALEPHANT_API_BASE_URL=https://alephant.io
ALEPHANT_VIRTUAL_KEY=vk-...
```

VK mode can read:

* current key scope
* current key budget status
* recent key-scoped requests
* usage summary, daily costs, and model costs for the allowed scope

It cannot create keys, modify budgets, view other departments, or manage workspace policies.

## Manager Mode

Use Manager mode for FinOps administrators, workspace owners, and team leads who need workspace-level analytics and management operations.

```bash
ALEPHANT_API_BASE_URL=https://alephant.io
ALEPHANT_PAT=pat_...
ALEPHANT_WORKSPACE_ID=00000000-0000-0000-0000-000000000000
```

Manager mode can:

* list, create, update, and revoke virtual keys
* inspect workspace, department, agent, member, and model analytics
* inspect subscription and budget status
* set workspace budget policies
* run composite analysis tools such as anomaly detection, executive dashboards, spend drill-downs, idle resource scans, and entity period comparisons

Write tools such as `create_virtual_key`, `update_key_budget`, `revoke_virtual_key`, and `set_budget_policy` should only be called after explicit user confirmation.

## Client-Side Rate Limit

| Variable                  | Required | Default | Description                                                                                                                           |
| ------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `ALEPHANT_RATE_LIMIT_RPM` | No       | `60`    | Maximum HTTP-bound tool calls per minute. Set to `0` to disable client-side throttling. Invalid or negative values fall back to `60`. |

This throttling is local to the MCP server process and is separate from any API-side rate limits.

## Transport

The current npm package runs as a **local stdio MCP server**:

```bash
npx -y @alephantai/mcp
```

Use one MCP server entry per credential scope. For multiple workspaces, create multiple entries with unique names and different `ALEPHANT_PAT` / `ALEPHANT_WORKSPACE_ID` values.

## CLI Audit Mode

The `alephant-mcp` binary also supports a one-shot audit run:

```bash
npx --yes --package=@alephantai/mcp alephant-mcp --audit
```

In VK mode, audit prints cockpit `scope` and `usage-summary` for the billing cycle. In Manager mode, audit prints the workspace id and workspace overview.

> Configure Alephant MCP credentials, execution modes, throttling, and audit runs