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

# Usage Guide & Prompts

> Use Alephant MCP with natural language, tool templates, and built-in prompts

## Interaction Principles

When asking an AI assistant to use Alephant MCP:

1. **Name the scope**: current virtual key, whole workspace, a department UUID, an agent UUID, or a member UUID.
2. **Name the time window**: `24h`, `7d`, `30d`, or `billing_cycle` for shared usage tools; some Manager analytics also support `3m`, `6m`, and `12m`.
3. **Require tool use for live data**: say "Use the enabled Alephant MCP tools; do not guess."
4. **Confirm writes explicitly**: creating keys, updating budgets, revoking keys, and setting budget policies are Manager-mode write operations.

## Natural Language Examples

| Intent              | Example                                                                 |
| ------------------- | ----------------------------------------------------------------------- |
| Usage summary       | "Use Alephant MCP to show usage summary for the current billing cycle." |
| Daily trend         | "Use Alephant MCP to show daily cost trend for the last 7 days."        |
| Model cost          | "Use Alephant MCP to break down spend by model for the last 30 days."   |
| VK scope            | "Use Alephant MCP to tell me what scope my virtual key is bound to."    |
| VK budget           | "Use Alephant MCP to show how much budget is left this billing cycle."  |
| Workspace dashboard | "Use Alephant MCP to build an executive dashboard for the workspace."   |
| Cost anomaly        | "Use Alephant MCP to diagnose cost anomalies for the last 30 days."     |
| Idle resources      | "Use Alephant MCP to find idle virtual keys and agents."                |
| Key management      | "Use Alephant MCP to list all virtual keys and budgets."                |
| Audit               | "Run Alephant's cost audit report for this week."                       |

## Command Templates

The MCP protocol does not register slash commands in the chat box. These templates are suggested text prefixes to send to the assistant.

### Shared tools

| Template                                                                | Typical tools                                   |
| ----------------------------------------------------------------------- | ----------------------------------------------- |
| `/alephant-usage Show usage summary for this billing cycle`             | `get_usage_summary` with `period=billing_cycle` |
| `/alephant-usage Total consumption and daily trend for the last 7 days` | `get_usage_summary`, `get_daily_costs`          |
| `/alephant-usage Cost by model for the last 30 days`                    | `get_cost_by_model`                             |
| `/alephant-models List currently available models`                      | `list_available_models`                         |
| `/alephant-health Check the Alephant connection`                        | `check_alephant_connection`                     |

### VK mode

| Template                                                      | Tool                     |
| ------------------------------------------------------------- | ------------------------ |
| `/alephant-vk What is the scope bound to my current key`      | `get_my_scope`           |
| `/alephant-vk How much budget is left for this billing cycle` | `get_my_budget`          |
| `/alephant-vk Show recent requests for this key`              | `get_my_recent_requests` |

### Manager mode

| Template                                                                                        | Typical tools                 |
| ----------------------------------------------------------------------------------------------- | ----------------------------- |
| `/alephant-mgr Workspace overview`                                                              | `get_workspace_overview`      |
| `/alephant-mgr Workspace budget status`                                                         | `get_workspace_budget_status` |
| `/alephant-mgr Real-time 24h dashboard`                                                         | `get_live_24h`                |
| `/alephant-mgr Usage time series for cost over 30 days`                                         | `get_usage_timeseries`        |
| `/alephant-mgr Seven-day sparkline trends`                                                      | `get_sparklines`              |
| `/alephant-mgr List all virtual keys and budgets`                                               | `list_virtual_keys`           |
| `/alephant-mgr Create a virtual key after I confirm label, master key, budget, and RPM`         | `create_virtual_key`          |
| `/alephant-mgr Update key [uuid] budget to [cents] and action [alert_only or block]`            | `update_key_budget`           |
| `/alephant-mgr Revoke key [uuid] after I confirm`                                               | `revoke_virtual_key`          |
| `/alephant-mgr List departments`                                                                | `list_departments`            |
| `/alephant-mgr Department [uuid] analytics for the last 30 days`                                | `get_department_analytics`    |
| `/alephant-mgr List agents`                                                                     | `list_agents`                 |
| `/alephant-mgr Agent [uuid] analytics for the last 7 days`                                      | `get_agent_analytics`         |
| `/alephant-mgr List members`                                                                    | `list_members`                |
| `/alephant-mgr Member [uuid] analytics for the last 30 days`                                    | `get_member_analytics`        |
| `/alephant-mgr Subscription and billing cycle info`                                             | `get_subscription_info`       |
| `/alephant-mgr Set workspace budget policy to [amount] cents with action [alert_only or block]` | `set_budget_policy`           |
| `/alephant-mgr Diagnose cost anomalies for the last 30 days`                                    | `diagnose_cost_anomaly`       |
| `/alephant-mgr Build executive dashboard`                                                       | `get_executive_dashboard`     |
| `/alephant-mgr Drill down workspace spend by department`                                        | `drill_down_spend`            |
| `/alephant-mgr Find idle keys and agents`                                                       | `find_idle_resources`         |
| `/alephant-mgr Compare [department, agent, or member] [uuid] current vs previous 30 days`       | `compare_entity_periods`      |

## Built-In Prompts

| Prompt                   | Mode         | Arguments          | Description |                                                                                        |                                                                                             |                                                                                                                         |
| ------------------------ | ------------ | ------------------ | ----------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `cost_audit_report`      | VK + Manager | \`period=weekly    | monthly     | quarterly\`                                                                            | Produces a structured Markdown audit with findings, breakdowns, risks, and recommendations. |                                                                                                                         |
| `cost_optimization`      | Manager      | \`focus=models     | departments | agents                                                                                 | general\`                                                                                   | Produces prioritized recommendations using dashboard, anomaly, drill-down, comparison, idle-resource, and budget tools. |
| `workspace_health_check` | Manager      | \`urgency=quick    | thorough\`  | Checks live health, trends, anomalies, success rate, and latency depending on urgency. |                                                                                             |                                                                                                                         |
| `cost_deep_dive`         | Manager      | \`target=workspace | department  | agent`, optional `target\_id\`                                                         | Investigates root causes and impact for workspace, department, or agent spend.              |                                                                                                                         |

Example request:

> Use Alephant MCP prompt `cost_audit_report` with `period=weekly`. Do not assume data that tools did not return.

## Notes

* `get_usage_summary` returns `total_tokens.input` as prompt/input tokens and `total_tokens.output` as completion/output tokens.
* `get_cost_by_model` is filtered to the current VK's bound agent/member scope when applicable; unbound keys use workspace scope.
* `get_my_recent_requests` returns live rows with `tokens_in`, `tokens_out`, `status`, `latency_ms`, and `created_at`. `degraded=true` means the backend, Collector, or requested scope could not provide live rows.
* These are response behavior clarifications only; the MCP tool schema is unchanged.
* `get_request_logs` is not available in this MCP build.
* Manager composite tools may call multiple Alephant API endpoints and return partial metadata when one step fails.
* For persistent dashboards or charts, use the Alephant Cockpit UI after the MCP tools identify the relevant scope and time window.

> Use Alephant MCP with natural language, tool templates, and built-in prompts