> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For full documentation content, see https://developers.alephant.io/llms-full.txt.

# Introduction

> Overview of Alephant MCP, its modes, tools, and prompts

**Alephant MCP Server** is a local Model Context Protocol server for Alephant BYO-KEY. It lets AI clients such as Cursor, Claude Desktop, Claude Code, Codex, OpenCode, and other MCP hosts query FinOps data and, when authorized, manage workspace keys and policies without leaving the assistant workflow.

The package is published as `@alephantai/mcp` and exposes the `alephant-mcp` binary. The current implementation runs over local stdio transport.

## What Alephant MCP Does

Alephant MCP gives an AI assistant a controlled interface to Alephant's SaaS API:

* **Usage and cost analysis**: usage summaries, daily cost trends, model-level cost, rolling 24-hour snapshots, and time series.
* **Budget visibility**: key-scoped budget status in VK mode and workspace budget status in Manager mode.
* **Workspace management**: virtual key management, members, departments, agents, subscription details, and budget policies in Manager mode.
* **FinOps workflows**: built-in prompts for audits, optimization, workspace health checks, and cost deep dives.

## Execution Modes

Alephant MCP chooses its permission mode from environment variables at startup.

| Mode                 | Credentials                              | Scope                                            | Tool count |
| -------------------- | ---------------------------------------- | ------------------------------------------------ | ---------- |
| **Virtual Key (VK)** | `ALEPHANT_VIRTUAL_KEY`                   | Read-only cockpit data scoped to one virtual key | 8          |
| **Manager**          | `ALEPHANT_PAT` + `ALEPHANT_WORKSPACE_ID` | Workspace-wide read/write management             | 27         |

If `ALEPHANT_PAT` is set, Manager mode takes precedence. If neither credential set is provided, the server exits with an error and does not fall back to mock data.

## MCP Surface

The current server registers **Tools** and **Prompts**.

### Shared tools

Available in both modes:

* `check_alephant_connection`
* `get_usage_summary`
* `get_daily_costs`
* `get_cost_by_model`
* `list_available_models`

### VK-only tools

* `get_my_scope`
* `get_my_budget`
* `get_my_recent_requests`

### Manager-only tools

* Virtual keys: `list_virtual_keys`, `create_virtual_key`, `update_key_budget`, `revoke_virtual_key`
* Workspace analytics: `get_workspace_overview`, `get_workspace_budget_status`, `get_live_24h`, `get_usage_timeseries`, `get_sparklines`
* Entities: `list_agents`, `get_agent_analytics`, `list_members`, `get_member_analytics`, `list_departments`, `get_department_analytics`
* Billing and policy: `get_subscription_info`, `set_budget_policy`
* Composite FinOps analysis: `diagnose_cost_anomaly`, `get_executive_dashboard`, `drill_down_spend`, `find_idle_resources`, `compare_entity_periods`

`get_request_logs` is not included in this MCP build because the backend route is JWT-only.

### Prompts

| Prompt                   | Mode         | Purpose                                                       |
| ------------------------ | ------------ | ------------------------------------------------------------- |
| `cost_audit_report`      | VK + Manager | Structured weekly, monthly, or quarterly cost audit           |
| `cost_optimization`      | Manager      | Prioritized cost optimization recommendations                 |
| `workspace_health_check` | Manager      | Quick or thorough workspace health assessment                 |
| `cost_deep_dive`         | Manager      | Root-cause analysis for workspace, department, or agent spend |

## Typical Workflow

Ask the assistant a natural-language question, and instruct it to use the enabled Alephant MCP tools when the answer depends on live usage, budget, key, department, agent, or model data.

Example:

> Use Alephant MCP to show the last 30 days of model cost, identify any anomalies, and recommend the top three actions.

In Manager mode, the assistant can combine `get_cost_by_model`, `diagnose_cost_anomaly`, `drill_down_spend`, and `find_idle_resources` to produce a data-backed FinOps report.