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

# Client Integration

> Configure Alephant MCP in Cursor, Claude Desktop, Codex, OpenCode, and Claude Code

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

```bash
npm install -g @alephantai/mcp
```

Global installation is optional. The recommended client command is:

```bash
npx -y @alephantai/mcp
```

## Environment Variables

Choose one credential mode per MCP server entry.

| Variable                  | Required     | Description                                                                  |
| ------------------------- | ------------ | ---------------------------------------------------------------------------- |
| `ALEPHANT_API_BASE_URL`   | Yes          | SaaS API base URL, for example `https://alephant.io`                         |
| `ALEPHANT_VIRTUAL_KEY`    | VK mode      | Virtual key for read-only cockpit-scoped tools                               |
| `ALEPHANT_PAT`            | Manager mode | Personal Access Token                                                        |
| `ALEPHANT_WORKSPACE_ID`   | Manager mode | Workspace UUID for the PAT                                                   |
| `ALEPHANT_RATE_LIMIT_RPM` | No           | Local HTTP tool-call limit per minute. Defaults to `60`; set `0` to disable. |

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

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

### Manager mode

```json
{
  "mcpServers": {
    "alephant-workspace": {
      "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"
      }
    }
  }
}
```

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

```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 environment with:

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

Verify the server registration:

```bash
codex mcp list
codex mcp get alephant
```

## OpenCode

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

```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

Add Alephant as a local stdio server:

```bash
claude 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
claude mcp list
claude mcp get alephant
```

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

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

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:

```bash
npm start
node ./bin/alephant-mcp.js
```

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

```bash
cd ..
npx -y @alephantai/mcp
```

If bin resolution fails, use the explicit package form:

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

## Scheduled Audit

For a local weekly audit, add a cron entry:

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

> Configure Alephant MCP in Cursor, Claude Desktop, Codex, OpenCode, and Claude Code