Client Integration

Alephant MCP is distributed through npm as @alephantai/mcp. Most clients can run it directly with npx.

$
npm install -g @alephantai/mcp

Global installation is optional. The recommended client command is:

$
npx -y @alephantai/mcp

Environment Variables

Choose one credential mode per MCP server entry.

If both ALEPHANT_PAT and ALEPHANT_VIRTUAL_KEY are present, the server uses Manager mode.

Cursor and Claude Desktop

Use the same mcpServers shape for clients that read JSON MCP configuration.

Virtual Key mode

1
{
2
  "mcpServers": {
3
    "alephant": {
4
      "command": "npx",
5
      "args": ["-y", "@alephantai/mcp"],
6
      "env": {
7
        "ALEPHANT_API_BASE_URL": "https://alephant.ai",
8
        "ALEPHANT_VIRTUAL_KEY": "vk-..."
9
      }
10
    }
11
  }
12
}

Manager mode

1
{
2
  "mcpServers": {
3
    "alephant-workspace": {
4
      "command": "npx",
5
      "args": ["-y", "@alephantai/mcp"],
6
      "env": {
7
        "ALEPHANT_API_BASE_URL": "https://alephant.ai",
8
        "ALEPHANT_PAT": "pat_...",
9
        "ALEPHANT_WORKSPACE_ID": "00000000-0000-0000-0000-000000000000"
10
      }
11
    }
12
  }
13
}

For multiple workspaces, duplicate the server entry with a unique name such as alephant-prod and alephant-staging.

Codex

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

1
[mcp_servers.alephant]
2
command = "npx"
3
args = ["-y", "@alephantai/mcp"]
4
env = {
5
  ALEPHANT_API_BASE_URL = "https://alephant.ai",
6
  ALEPHANT_VIRTUAL_KEY = "vk-..."
7
}
8
startup_timeout_sec = 20
9
tool_timeout_sec = 120

For Manager mode, replace the VK environment with:

1
env = {
2
  ALEPHANT_API_BASE_URL = "https://alephant.ai",
3
  ALEPHANT_PAT = "pat_...",
4
  ALEPHANT_WORKSPACE_ID = "00000000-0000-0000-0000-000000000000"
5
}

Verify the server registration:

$
codex mcp list
$
codex mcp get alephant

OpenCode

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

1
{
2
  "$schema": "https://opencode.ai/config.json",
3
  "mcp": {
4
    "alephant": {
5
      "type": "local",
6
      "command": ["npx", "-y", "@alephantai/mcp"],
7
      "enabled": true,
8
      "environment": {
9
        "ALEPHANT_API_BASE_URL": "https://alephant.ai",
10
        "ALEPHANT_VIRTUAL_KEY": "vk-..."
11
      }
12
    }
13
  }
14
}

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

Claude Code

Add Alephant as a local stdio server:

$
claude mcp add-json alephant '{"type":"stdio","command":"npx","args":["-y","@alephantai/mcp"],"env":{"ALEPHANT_API_BASE_URL":"https://alephant.ai","ALEPHANT_VIRTUAL_KEY":"vk-..."}}' --scope user
$
claude mcp list
$
claude mcp get alephant

For project-shared configuration, create .mcp.json in the project root:

1
{
2
  "mcpServers": {
3
    "alephant": {
4
      "type": "stdio",
5
      "command": "npx",
6
      "args": ["-y", "@alephantai/mcp"],
7
      "env": {
8
        "ALEPHANT_API_BASE_URL": "https://alephant.ai",
9
        "ALEPHANT_VIRTUAL_KEY": "vk-..."
10
      }
11
    }
12
  }
13
}

For Manager mode, replace the VK environment with ALEPHANT_PAT and ALEPHANT_WORKSPACE_ID.

Local Development Troubleshooting

When developing inside the alephant-mcp repository clone, do not use npx -y @alephantai/mcp from the repo root to smoke test the published package. npm may resolve the current local project instead of the registry package.

Use one of these commands in the clone:

$
npm start
$
node ./bin/alephant-mcp.js

To test the published package with npx, run from a different directory such as the parent folder:

$
cd ..
$
npx -y @alephantai/mcp

If bin resolution fails, use the explicit package form:

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

Scheduled Audit

For a local weekly audit, add a cron entry:

1
0 9 * * 1 npx --yes --package=@alephantai/mcp alephant-mcp --audit >> ./AUDIT.md