Configuration & Execution

View as Markdown

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

Required Base URL

VariableRequiredDescription
ALEPHANT_API_BASE_URLYesSaaS API base URL, for example https://alephant.ai. A trailing slash is accepted and normalized.

Permission Modes

ModeRequired variablesPermissionsTool count
Virtual Key (VK)ALEPHANT_VIRTUAL_KEYRead-only cockpit scope for one virtual key8
ManagerALEPHANT_PAT + ALEPHANT_WORKSPACE_IDWorkspace-wide read/write access27

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.

$ALEPHANT_API_BASE_URL=https://alephant.ai
$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.

$ALEPHANT_API_BASE_URL=https://alephant.ai
$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

VariableRequiredDefaultDescription
ALEPHANT_RATE_LIMIT_RPMNo60Maximum 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:

$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:

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