{
  "markdown": "# Alephant MCP Server\n\nModel Context Protocol server for **Alephant BYO-KEY**: FinOps metrics, virtual keys, and workspace analytics from Cursor, Claude Desktop, or any MCP host.\n\n## Modes\n\n| Mode | Environment | Tools |\n|------|-------------|--------|\n| **VK** | `ALEPHANT_VIRTUAL_KEY` | Cockpit-scoped usage + 3 VK tools (8 tools total incl. shared) |\n| **Manager** | `ALEPHANT_PAT` + `ALEPHANT_WORKSPACE_ID` | Workspace-wide management (27 tools total incl. shared) |\n\nPAT takes precedence when `ALEPHANT_PAT` is non-empty. If neither VK nor PAT is set, the process exits with an error (no mock data).\n\n**Required (both modes):** `ALEPHANT_API_BASE_URL`  \n**Optional:** `ALEPHANT_RATE_LIMIT_RPM` (default `60`, use `0` to disable client-side throttling)\n\n### Windows / `npx` troubleshooting\n\n**From this repo’s root (`alephant-mcp/`):** do **not** use `npx -y @alephantai/mcp` to “smoke test” the published package. npm treats the current directory as the local `@alephantai/mcp` project and does **not** link the root package’s `bin` into `node_modules/.bin`, so Windows then fails with `'alephant-mcp' is not recognized` (or the Chinese CMD equivalent).\n\nUse one of these instead while developing in the clone:\n\n```powershell\nnpm start\n# or\nnode .\\bin\\alephant-mcp.js\n```\n\nTo verify `npx` the same way end users do, run it from **any other directory** (e.g. the parent folder):\n\n```powershell\ncd ..\nnpx -y @alephantai/mcp\n```\n\n**From a normal project folder** (after `npm install @alephantai/mcp`), you can also run:\n\n```powershell\nnode .\\node_modules\\@alephantai\\mcp\\bin\\alephant-mcp.js\n```\n\nIf `npx -y @alephantai/mcp` still fails outside the clone, try:\n\n```powershell\nnpx --yes --package=@alephantai/mcp alephant-mcp\n```\n\nPublished packages **0.0.2+** include the `bin/alephant-mcp.js` shim for reliable npm bin resolution when installed from the registry.\n\n## MCP client config\n\nAlephant MCP is a local stdio server. Use one server entry per credential scope. For multiple workspaces, create multiple entries with different names and environment variables.\n\n### Cursor / Claude Desktop\n\n**Virtual Key (read-only / scoped cockpit):**\n\n```json\n{\n  \"mcpServers\": {\n    \"alephant\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@alephantai/mcp\"],\n      \"env\": {\n        \"ALEPHANT_API_BASE_URL\": \"https://alephant.io\",\n        \"ALEPHANT_VIRTUAL_KEY\": \"vk-...\"\n      }\n    }\n  }\n}\n```\n\n**Personal Access Token (manager):**\n\n```json\n{\n  \"mcpServers\": {\n    \"alephant-workspace-a\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@alephantai/mcp\"],\n      \"env\": {\n        \"ALEPHANT_API_BASE_URL\": \"https://alephant.io\",\n        \"ALEPHANT_PAT\": \"pat_...\",\n        \"ALEPHANT_WORKSPACE_ID\": \"00000000-0000-0000-0000-000000000000\"\n      }\n    }\n  }\n}\n```\n\nUse **separate `mcpServers` entries** per workspace when you have multiple PATs.\n\n### Codex\n\nAdd a stdio MCP server in `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.alephant]\ncommand = \"npx\"\nargs = [\"-y\", \"@alephantai/mcp\"]\nenv = {\n  ALEPHANT_API_BASE_URL = \"https://alephant.io\",\n  ALEPHANT_VIRTUAL_KEY = \"vk-...\"\n}\nstartup_timeout_sec = 20\ntool_timeout_sec = 120\n```\n\nFor Manager mode, replace the VK env with:\n\n```toml\nenv = {\n  ALEPHANT_API_BASE_URL = \"https://alephant.io\",\n  ALEPHANT_PAT = \"pat_...\",\n  ALEPHANT_WORKSPACE_ID = \"00000000-0000-0000-0000-000000000000\"\n}\n```\n\nVerify with:\n\n```bash\ncodex mcp list\ncodex mcp get alephant\n```\n\n### OpenCode\n\nAdd a local MCP server under `mcp` in your OpenCode config, for example `opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"mcp\": {\n    \"alephant\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@alephantai/mcp\"],\n      \"enabled\": true,\n      \"environment\": {\n        \"ALEPHANT_API_BASE_URL\": \"https://alephant.io\",\n        \"ALEPHANT_VIRTUAL_KEY\": \"vk-...\"\n      }\n    }\n  }\n}\n```\n\nFor Manager mode, use `ALEPHANT_PAT` and `ALEPHANT_WORKSPACE_ID` in `environment` instead of `ALEPHANT_VIRTUAL_KEY`.\n\n### Claude Code\n\nUse the CLI to add Alephant as a local stdio server:\n\n```bash\nclaude mcp add-json alephant '{\"type\":\"stdio\",\"command\":\"npx\",\"args\":[\"-y\",\"@alephantai/mcp\"],\"env\":{\"ALEPHANT_API_BASE_URL\":\"https://alephant.io\",\"ALEPHANT_VIRTUAL_KEY\":\"vk-...\"}}' --scope user\nclaude mcp list\nclaude mcp get alephant\n```\n\nFor a shared project config, create `.mcp.json` in the project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"alephant\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@alephantai/mcp\"],\n      \"env\": {\n        \"ALEPHANT_API_BASE_URL\": \"https://alephant.io\",\n        \"ALEPHANT_VIRTUAL_KEY\": \"vk-...\"\n      }\n    }\n  }\n}\n```\n\nFor Manager mode, replace the VK env with `ALEPHANT_PAT` and `ALEPHANT_WORKSPACE_ID`.\n\n## CLI audit\n\n```bash\nnpx --yes --package=@alephantai/mcp alephant-mcp --audit\n```\n\n- **VK:** prints cockpit `scope` + `usage-summary` (billing cycle).  \n- **Manager:** prints workspace id + `GET /api/v1/analytics/overview`.\n\n## Tools (summary)\n\nShared (both modes): `check_alephant_connection`, `get_usage_summary`, `get_daily_costs`, `get_cost_by_model`, `list_available_models`  \nVK only: `get_my_scope`, `get_my_budget`, `get_my_recent_requests`  \nManager only: `get_workspace_overview`, `get_workspace_budget_status`, `list_virtual_keys`, `create_virtual_key`, `update_key_budget`, `revoke_virtual_key`, `list_agents`, `get_agent_analytics`, `list_members`, `get_member_analytics`, `list_departments`, `get_department_analytics`, `get_subscription_info`, `set_budget_policy`, `get_live_24h`, `get_usage_timeseries`, `get_sparklines`, `diagnose_cost_anomaly`, `get_executive_dashboard`, `drill_down_spend`, `find_idle_resources`, `compare_entity_periods`\n\n`get_request_logs` is **not** included (JWT-only backend route).\n\n## Prompts & resources\n\n- **cost_audit_report** — both modes  \n- **cost_optimization** — manager only\n\n## Documentation\n\n- **[中文：在 AI Agent 中如何使用 MCP](docs/zh-CN/agent-mcp-usage.md)** — 自然语言提问示例、`/alephant-…` 快捷模板、工具对照表  \n- **Marketplace submission**: see [`docs/marketplace-submission.md`](docs/marketplace-submission.md) for official MCP Registry, Smithery, and Glama submission notes.\n\n## Development\n\n```bash\nnpm install\nnpm test\nnpm run build\n```\n\n## Package\n\nPublished as **`@alephantai/mcp`** (`alephant-mcp` binary).\n",
  "bytes": 6249,
  "sha": "ae01e8279c7dc73901d5e6150cb11e6cc38c82be469600761e1a4f5a0b8566c2",
  "repo_slug": "alephantai/alephant-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_alephantai_alephant_mcp_4b9d4b46/readme"
}