# Client Integrations

# Client Integrations

Visa CLI runs a local MCP server. Install the CLI, complete setup, then run `visa-cli install <client>` to register it with the client that will use paid tools — that writes the correct config automatically. The manual config blocks below show the equivalent entry; replace `<npm root -g>` with the path printed by `npm root -g`.

## Install The CLI

macOS and Linux:

```bash
curl -fsSL https://app.visacli.sh/cli | bash
```

Windows PowerShell:

```powershell
iwr -useb https://app.visacli.sh/install.ps1 | iex
```

If the installer cannot run interactive setup, run:

```bash
visa-cli setup
```

## Automatic Client Install

The CLI knows the supported client ids:

```bash
visa-cli install --list
```

Install a specific client:

```bash
visa-cli install claude
visa-cli install claude-desktop
visa-cli install codex
visa-cli install cursor
visa-cli install windsurf
visa-cli install cline
visa-cli install roo-code
visa-cli install copilot
visa-cli install zed
```

Restart the client after installing so it reloads MCP servers.

## Claude Code

```bash
visa-cli install claude
```

Claude Code users can reconnect an already-open session with `/mcp`, then select `visa-cli` and reconnect. The `/mcp` command belongs inside Claude Code, not Terminal or PowerShell.

## Claude Desktop

```bash
visa-cli install claude-desktop
```

Manual config:

```json
{
  "mcpServers": {
    "visa-cli": {
      "command": "node",
      "args": ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
    }
  }
}
```

Restart the Claude desktop app after saving config.

## Codex

```bash
visa-cli install codex
```

Manual config:

```toml
[mcp_servers.visa-cli]
command = "node"
args = ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
```

If Codex sandboxing blocks `~/.codex/config.toml`, run `visa-cli install codex` from a normal terminal or grant filesystem access.

## Cursor

```bash
visa-cli install cursor
```

Manual config:

```json
{
  "mcpServers": {
    "visa-cli": {
      "command": "node",
      "args": ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
    }
  }
}
```

Restart Cursor after installing.

## Windsurf

```bash
visa-cli install windsurf
```

Manual config:

```json
{
  "mcpServers": {
    "visa-cli": {
      "command": "node",
      "args": ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
    }
  }
}
```

Restart Windsurf after installing.

## Cline

```bash
visa-cli install cline
```

Manual config:

```json
{
  "mcpServers": {
    "visa-cli": {
      "command": "node",
      "args": ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
    }
  }
}
```

Restart VS Code after installing.

## Roo Code

```bash
visa-cli install roo-code
```

Manual config:

```json
{
  "mcpServers": {
    "visa-cli": {
      "command": "node",
      "args": ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
    }
  }
}
```

Restart VS Code after installing.

## VS Code Copilot

```bash
visa-cli install copilot
```

Manual config:

```json
{
  "servers": {
    "visa-cli": {
      "command": "node",
      "args": ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
    }
  }
}
```

Restart VS Code after installing.

## Zed

```bash
visa-cli install zed
```

Manual config:

```json
{
  "context_servers": {
    "visa-cli": {
      "source": "custom",
      "command": "node",
      "args": ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
    }
  }
}
```

Restart Zed after installing.

## Other MCP Clients

Use this server entry when your client supports generic local MCP servers:

```json
{
  "mcpServers": {
    "visa-cli": {
      "command": "node",
      "args": ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
    }
  }
}
```

If your client uses another key name, keep the same command and args.

## Verify

Check local setup:

```bash
visa-cli status
```

If tools do not appear in your client, restart the client or reconnect the MCP server. You can re-run `visa-cli install <client>` to rewrite the config.

## Headless Apps

For backend services and unattended agents, use a scoped Visa Key instead of an MCP client session:

```bash
visa-cli keys create my-demo-app --tools or-gpt-4o-mini --daily-cap 5 --total-cap 200
```

Then call `POST /v1/api/tools/:tool/execute` with `X-Api-Key` and an `Idempotency-Key`. See [Visa Key API](/docs/visa-key-api) for the route contract, retry rules, response codes, and key-management APIs.