# How do I add Immiscible's MCP server to Claude Code, Cursor or VS Code?

> One command in Claude Code, one JSON entry in Cursor, VS Code, Windsurf, Codex or Gemini CLI, or a custom connector in Claude and ChatGPT. The server is at /mcp and takes an agent key or OAuth sign-in.

Source: https://immiscible.fly.dev/docs/answers/add-the-mcp-server

The MCP server is at `https://immiscible.fly.dev/mcp` (Streamable HTTP), and it takes an agent key as a bearer token or an OAuth sign-in. In Claude Code it is one command, `claude mcp add --transport http immiscible https://immiscible.fly.dev/mcp --header "Authorization: Bearer $IMMISCIBLE_AGENT_KEY"`; in other clients it is one JSON entry, below.

## 1. Get an agent key

```bash
npx immiscible init --yes
```

This writes `IMMISCIBLE_URL` and `IMMISCIBLE_AGENT_KEY` to `.env` (and adds `.env` to `.gitignore`). An AI coding agent can run it too: see [can an AI coding agent install it itself?](#can-an-ai-coding-agent-install-it-itself). Load the key into your shell with `export $(grep IMMISCIBLE_ .env | xargs)`, or skip the key and sign in with OAuth where the client supports it.

## 2. Add the server to your client

```bash
npx immiscible mcp                    # every client's setup, for your server
npx immiscible mcp --client cursor    # one client; --json for a script
```

It prints the entries below for your own server address, and changes nothing.

Claude Code:

```bash
claude mcp add --transport http immiscible https://immiscible.fly.dev/mcp \
  --header "Authorization: Bearer $IMMISCIBLE_AGENT_KEY"
```

.mcp.json (Claude Code, shared):

```json
{
  "mcpServers": {
    "immiscible": {
      "type": "http",
      "url": "https://immiscible.fly.dev/mcp",
      "headers": { "Authorization": "Bearer ${IMMISCIBLE_AGENT_KEY}" }
    }
  }
}
```

.cursor/mcp.json:

```json
{
  "mcpServers": {
    "immiscible": {
      "url": "https://immiscible.fly.dev/mcp",
      "headers": { "Authorization": "Bearer ${env:IMMISCIBLE_AGENT_KEY}" }
    }
  }
}
```

.vscode/mcp.json:

```json
{
  "inputs": [
    { "type": "promptString", "id": "immiscible-agent-key", "description": "Immiscible agent key (ask_...)", "password": true }
  ],
  "servers": {
    "immiscible": {
      "type": "http",
      "url": "https://immiscible.fly.dev/mcp",
      "headers": { "Authorization": "Bearer ${input:immiscible-agent-key}" }
    }
  }
}
```

Windsurf (Devin Desktop):

```json
{
  "mcpServers": {
    "immiscible": {
      "serverUrl": "https://immiscible.fly.dev/mcp",
      "headers": { "Authorization": "Bearer ${env:IMMISCIBLE_AGENT_KEY}" }
    }
  }
}
```

Codex CLI:

```toml
[mcp_servers.immiscible]
url = "https://immiscible.fly.dev/mcp"
bearer_token_env_var = "IMMISCIBLE_AGENT_KEY"
```

- **Claude Code**: the command stores the header for you. `.mcp.json` in a shared project expands `${IMMISCIBLE_AGENT_KEY}` from each person's environment, and Claude Code asks each person to approve the server once.
- **Cursor**: `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project. `npx immiscible mcp --client cursor` also prints a one-click install link.
- **VS Code** (GitHub Copilot agent mode): `code --add-mcp '{"name":"immiscible","type":"http","url":"https://immiscible.fly.dev/mcp"}'` adds it with OAuth sign-in instead of a key; `npx immiscible mcp --client vscode` also prints a `vscode:mcp/install` link.
- **Windsurf** (now Devin Desktop): `~/.config/devin/mcp_config.json` (on Windows `%APPDATA%\devin\mcp_config.json`; older Windsurf releases read `~/.codeium/windsurf/mcp_config.json`).
- **Codex CLI**: `codex mcp add immiscible --url https://immiscible.fly.dev/mcp --bearer-token-env-var IMMISCIBLE_AGENT_KEY` writes the entry above.
- **Gemini CLI**: `gemini mcp add --transport http -H "Authorization: Bearer $IMMISCIBLE_AGENT_KEY" immiscible https://immiscible.fly.dev/mcp`, or the Gemini extension in `packages/immiscible-gemini`.
- **Claude Code plugin and Claude Desktop**: see [install in your assistant](https://immiscible.fly.dev/docs/ai-agents.md#install-in-your-assistant) for the plugin (hook, MCP server, skill and analyst) and the `.mcpb` bundle.
- **Claude, ChatGPT and other connector clients**: add `https://immiscible.fly.dev/mcp` as a custom connector and sign in. You choose which agent the connection acts as on the consent screen. See [connectors](https://immiscible.fly.dev/docs/guides/mcp-proxy.md#claude-and-chatgpt-as-connectors).

## 3. Check it works

```bash
claude mcp list        # Claude Code: immiscible should show as connected
npx immiscible doctor  # the server, the clock, the key and the hook
```

The client should list eleven tools: `request_payment`, `request_personal_data`, `authorize_action`, `check_action_status`, `explain_decision` and `settle_action`, and the AI spend analyst's `spend_summary`, `find_waste`, `unwatched_keys`, `set_budget` and `revoke_key`. What each is for is in [the MCP server](https://immiscible.fly.dev/docs/ai-agents.md#the-mcp-server).

## Can an AI coding agent install it itself?

Yes, with a person allowing the sign-in once. Every command runs without a terminal: input comes from flags, `--json` prints one object, and each outcome has its own [exit code](https://immiscible.fly.dev/docs/cli.md#exit-codes).

```bash
npx immiscible login --json        # line 1: a link for the person to open; line 2, once they allow it: the result
npx immiscible init --yes --json   # creates the agent and its rule, writes .env, installs the Claude Code hook, tests the gate
npx immiscible mcp --client claude-code --json
npx immiscible doctor --json       # exit 0 when nothing failed
```

The agent should show the person the `verification_uri_complete` from the first line and wait; nothing is allowed until a person signs in and approves in the browser. In CI, use a token instead: `IMMISCIBLE_TOKEN` from `immiscible token create --name ci`. Exit code `3` means not signed in, `4` means a flag is needed (the error names it), and `10` means the agent's rule waits for another owner to confirm.

## Is the MCP server enough on its own?

No. Through the MCP server the model asks before it acts, and a model can choose not to ask. For Claude Code, add the [hook](https://immiscible.fly.dev/docs/guides/mcp-proxy.md#the-claude-code-hook), which Claude Code runs before every tool call whatever the model decides (`npx immiscible init` installs it). For other tools, put them behind the [MCP proxy](https://immiscible.fly.dev/docs/guides/mcp-proxy.md), which holds their credentials so the agent has no other way in.

## Which clients has this been tested with?

The server, the Claude Code command, `.mcp.json` and the Claude Code plugin are tested against Claude Code 2.1, the Gemini extension with `gemini extensions validate`, and the Desktop bundle with the MCPB tools. Cursor's agent reads the Cursor entry (running it needs a Cursor account). The Codex, VS Code and Windsurf entries follow each client's documentation as of October 2026 and are not yet tested; if a client changes its format, `npx immiscible mcp` is where we fix it.