Introduction

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.

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

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.