Alephant MCP Server

Model Context Protocol server for Alephant BYO-KEY: FinOps metrics, virtual keys, and workspace analytics from Cursor, Claude Desktop, or any MCP host.

Modes

PAT takes precedence when ALEPHANT_PAT is non-empty. If neither VK nor PAT is set, the process exits with an error (no mock data).

Required (both modes): ALEPHANT_API_BASE_URL
Optional: ALEPHANT_RATE_LIMIT_RPM (default 60, use 0 to disable client-side throttling)

Windows / npx troubleshooting

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

Use one of these instead while developing in the clone:

npm start
# or
node .\bin\alephant-mcp.js

To verify npx the same way end users do, run it from any other directory (e.g. the parent folder):

cd ..
npx -y @alephantai/mcp

From a normal project folder (after npm install @alephantai/mcp), you can also run:

node .\node_modules\@alephantai\mcp\bin\alephant-mcp.js

If npx -y @alephantai/mcp still fails outside the clone, try:

npx --yes --package=@alephantai/mcp alephant-mcp

Published packages 0.0.2+ include the bin/alephant-mcp.js shim for reliable npm bin resolution when installed from the registry.

MCP client config

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

Cursor / Claude Desktop

Virtual Key (read-only / scoped cockpit):

{
  "mcpServers": {
    "alephant": {
      "command": "npx",
      "args": ["-y", "@alephantai/mcp"],
      "env": {
        "ALEPHANT_API_BASE_URL": "https://alephant.io",
        "ALEPHANT_VIRTUAL_KEY": "vk-..."
      }
    }
  }
}

Personal Access Token (manager):

{
  "mcpServers": {
    "alephant-workspace-a": {
      "command": "npx",
      "args": ["-y", "@alephantai/mcp"],
      "env": {
        "ALEPHANT_API_BASE_URL": "https://alephant.io",
        "ALEPHANT_PAT": "pat_...",
        "ALEPHANT_WORKSPACE_ID": "00000000-0000-0000-0000-000000000000"
      }
    }
  }
}

Use separate mcpServers entries per workspace when you have multiple PATs.

Codex

Add a stdio MCP server in ~/.codex/config.toml:

[mcp_servers.alephant]
command = "npx"
args = ["-y", "@alephantai/mcp"]
env = {
  ALEPHANT_API_BASE_URL = "https://alephant.io",
  ALEPHANT_VIRTUAL_KEY = "vk-..."
}
startup_timeout_sec = 20
tool_timeout_sec = 120

For Manager mode, replace the VK env with:

env = {
  ALEPHANT_API_BASE_URL = "https://alephant.io",
  ALEPHANT_PAT = "pat_...",
  ALEPHANT_WORKSPACE_ID = "00000000-0000-0000-0000-000000000000"
}

Verify with:

codex mcp list
codex mcp get alephant

OpenCode

Add a local MCP server under mcp in your OpenCode config, for example opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "alephant": {
      "type": "local",
      "command": ["npx", "-y", "@alephantai/mcp"],
      "enabled": true,
      "environment": {
        "ALEPHANT_API_BASE_URL": "https://alephant.io",
        "ALEPHANT_VIRTUAL_KEY": "vk-..."
      }
    }
  }
}

For Manager mode, use ALEPHANT_PAT and ALEPHANT_WORKSPACE_ID in environment instead of ALEPHANT_VIRTUAL_KEY.

Claude Code

Use the CLI to add Alephant as a

... View full README on GitHub