bilinc 2.3.0__tar.gz → 2.3.3__tar.gz

{bilinc-2.3.0/src/bilinc.egg-info → bilinc-2.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bilinc
-Version: 2.3.0
+Version: 2.3.3
 Summary: Cloud-only memory SDK and MCP adapter for autonomous agents
 Author: Bilinc Team
 License-Expression: BUSL-1.1
@@ -56,7 +56,7 @@ Dynamic: license-file
 
 Retrieval answers *"what is similar to this?"*. Long-running agents also need to answer *"who wrote this state, was it verified, did it contradict what we already knew, and can we undo it?"* — that is the layer Bilinc provides.
 
-Bilinc 2.3.0 on PyPI is the public cloud-only package: a thin Python SDK, CLI, and MCP adapter for Bilinc Cloud. It does not ship the local StatePlane, storage backends, eval, observability, integrations, or server runtime internals.
+Bilinc 2.3.3 on PyPI is the public cloud-only package: a thin Python SDK, CLI, and MCP adapter for Bilinc Cloud. It does not ship the local StatePlane, storage backends, eval, observability, integrations, or server runtime internals.
 
 > **Frozen regression receipt** — LongMemEval-s cleaned retrieval fixture, 500 questions: **Hit@5 98.0%**, **NDCG@5 0.913**, no LLM reranker, no paid API. This is an isolated retrieval guardrail, not a current hosted SLA, end-to-end agent score, or competitor ranking — see [Benchmark receipt](#benchmark-receipt) for the full scope and qualification.
 
@@ -93,13 +93,30 @@ The fastest path is `pip install -U bilinc`, `bilinc login`, then `bilinc quickt
 | --- | --- |
 | A hosted memory API for an agent or MCP client | The public cloud-only package from PyPI |
 | Local StatePlane, SQLite/PostgreSQL, benchmarks, or internals | This repository and the [architecture guide](docs/architecture.md) |
-| A hosted MCP connection | The [MCP setup guide](https://bilinc.space/docs/mcp) |
+| A hosted MCP connection without a Python install | The [remote MCP setup guide](https://bilinc.space/docs/remote-mcp) |
 
 The public package is intentionally smaller than this repository. It does not bundle the internal StatePlane or local
 storage runtime.
 
 ## Start in 60 Seconds
 
+### Claude connector, without installing Python
+
+Open **Customize → Connectors → Add custom connector** in Claude, name it Bilinc,
+and paste `https://mcp.bilinc.space/mcp`. Sign in and choose read-only or read and
+write access. The setup guide is [bilinc.space/mcp](https://bilinc.space/mcp).
+
+For the remote connector in Claude Code:
+
+```bash
+claude mcp add --transport http --scope user bilinc https://mcp.bilinc.space/mcp
+```
+
+Then run `/mcp` and authenticate. The remote connector has ten tools; the Python
+stdio adapter below has eight. Both connect to hosted Bilinc memory.
+
+### SDK and CLI
+
 ```bash
 pip install -U bilinc
 bilinc login
@@ -119,7 +136,7 @@ Cloud status check.
 To reproduce this release exactly:
 
 ```bash
-pip install -U bilinc==2.3.0
+pip install -U bilinc==2.3.3
 ```
 
 If you prefer a browser guide, open https://bilinc.space/install and follow the
@@ -131,18 +148,28 @@ Bilinc exposes a standard Model Context Protocol server over **stdio**, so any
 MCP-compatible client can connect — Claude Code, Codex, Cursor, Hermes-Agent,
 opencode, and others.
 
+After `bilinc login`, let the CLI write the setup for your client:
+
+```bash
+bilinc mcp install --client claude-code     # prints a ready `claude mcp add ...` command
+bilinc mcp install --client claude-desktop  # prints the config and where Claude Desktop keeps it
+bilinc mcp install                          # plain mcpServers JSON for any other client
+```
+
 ```json
 {
   "mcpServers": {
     "bilinc": {
-      "command": "python",
-      "args": ["-m", "bilinc.cloud_mcp"],
-      "env": { "BILINC_API_KEY": "bil_live_..." }
+      "command": "/path/to/python3",
+      "args": ["-m", "bilinc.cloud_mcp"]
     }
   }
 }
 ```
 
+`command` is the interpreter that has Bilinc installed, and the adapter reads the key saved by `bilinc login`, so
+the config carries no key. On a machine without a saved key, add `"env": { "BILINC_API_KEY": "bil_live_..." }`.
+
 Eight tools — the core memory lifecycle, and nothing else:
 
 | Tool | What it does |

{bilinc-2.3.0 → bilinc-2.3.3}/README.md

@@ -14,7 +14,7 @@
 
 Retrieval answers *"what is similar to this?"*. Long-running agents also need to answer *"who wrote this state, was it verified, did it contradict what we already knew, and can we undo it?"* — that is the layer Bilinc provides.
 
-Bilinc 2.3.0 on PyPI is the public cloud-only package: a thin Python SDK, CLI, and MCP adapter for Bilinc Cloud. It does not ship the local StatePlane, storage backends, eval, observability, integrations, or server runtime internals.
+Bilinc 2.3.3 on PyPI is the public cloud-only package: a thin Python SDK, CLI, and MCP adapter for Bilinc Cloud. It does not ship the local StatePlane, storage backends, eval, observability, integrations, or server runtime internals.
 
 > **Frozen regression receipt** — LongMemEval-s cleaned retrieval fixture, 500 questions: **Hit@5 98.0%**, **NDCG@5 0.913**, no LLM reranker, no paid API. This is an isolated retrieval guardrail, not a current hosted SLA, end-to-end agent score, or competitor ranking — see [Benchmark receipt](#benchmark-receipt) for the full scope and qualification.
 
@@ -51,13 +51,30 @@ The fastest path is `pip install -U bilinc`, `bilinc login`, then `bilinc quickt
 | --- | --- |
 | A hosted memory API for an agent or MCP client | The public cloud-only package from PyPI |
 | Local StatePlane, SQLite/PostgreSQL, benchmarks, or internals | This repository and the [architecture guide](docs/architecture.md) |
-| A hosted MCP connection | The [MCP setup guide](https://bilinc.space/docs/mcp) |
+| A hosted MCP connection without a Python install | The [remote MCP setup guide](https://bilinc.space/docs/remote-mcp) |
 
 The public package is intentionally smaller than this repository. It does not bundle the internal StatePlane or local
 storage runtime.
 
 ## Start in 60 Seconds
 
+### Claude connector, without installing Python
+
+Open **Customize → Connectors → Add custom connector** in Claude, name it Bilinc,
+and paste `https://mcp.bilinc.space/mcp`. Sign in and choose read-only or read and
+write access. The setup guide is [bilinc.space/mcp](https://bilinc.space/mcp).
+
+For the remote connector in Claude Code:
+
+```bash
+claude mcp add --transport http --scope user bilinc https://mcp.bilinc.space/mcp
+```
+
+Then run `/mcp` and authenticate. The remote connector has ten tools; the Python
+stdio adapter below has eight. Both connect to hosted Bilinc memory.
+
+### SDK and CLI
+
 ```bash
 pip install -U bilinc
 bilinc login
@@ -77,7 +94,7 @@ Cloud status check.
 To reproduce this release exactly:
 
 ```bash
-pip install -U bilinc==2.3.0
+pip install -U bilinc==2.3.3
 ```
 
 If you prefer a browser guide, open https://bilinc.space/install and follow the
@@ -89,18 +106,28 @@ Bilinc exposes a standard Model Context Protocol server over **stdio**, so any
 MCP-compatible client can connect — Claude Code, Codex, Cursor, Hermes-Agent,
 opencode, and others.
 
+After `bilinc login`, let the CLI write the setup for your client:
+
+```bash
+bilinc mcp install --client claude-code     # prints a ready `claude mcp add ...` command
+bilinc mcp install --client claude-desktop  # prints the config and where Claude Desktop keeps it
+bilinc mcp install                          # plain mcpServers JSON for any other client
+```
+
 ```json
 {
   "mcpServers": {
     "bilinc": {
-      "command": "python",
-      "args": ["-m", "bilinc.cloud_mcp"],
-      "env": { "BILINC_API_KEY": "bil_live_..." }
+      "command": "/path/to/python3",
+      "args": ["-m", "bilinc.cloud_mcp"]
     }
   }
 }
 ```
 
+`command` is the interpreter that has Bilinc installed, and the adapter reads the key saved by `bilinc login`, so
+the config carries no key. On a machine without a saved key, add `"env": { "BILINC_API_KEY": "bil_live_..." }`.
+
 Eight tools — the core memory lifecycle, and nothing else:
 
 | Tool | What it does |

{bilinc-2.3.0 → bilinc-2.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bilinc"
-version = "2.3.0"
+version = "2.3.3"
 description = "Cloud-only memory SDK and MCP adapter for autonomous agents"
 readme = "README.md"
 license = "BUSL-1.1"

{bilinc-2.3.0 → bilinc-2.3.3}/src/bilinc/__init__.py

@@ -1,4 +1,4 @@
-"""Bilinc 2.3.0: cloud-only SDK for agent memory."""
+"""Bilinc 2.3.3: cloud-only SDK for agent memory."""
 
 from bilinc.client import (
     ACTIVATION_SIGNUP_URL,
@@ -25,7 +25,7 @@ from bilinc.client import (
     CloudClient,
 )
 
-__version__ = "2.3.0"
+__version__ = "2.3.3"
 version = __version__
 
 __all__ = [

{bilinc-2.3.0 → bilinc-2.3.3}/src/bilinc/cli/main.py

@@ -6,6 +6,8 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import shlex
+import subprocess
 import sys
 import time
 import webbrowser
@@ -64,16 +66,38 @@ def _print_start_guide(*, opened: bool = False) -> None:
     )
 
 
+MCP_KEY_PLACEHOLDER = "bil_live_..."
+
+
+def _mcp_server_entry() -> dict[str, Any]:
+    # The absolute interpreter works where a bare `python` does not: macOS ships
+    # only python3, and Claude Desktop launches servers without the shell PATH.
+    entry: dict[str, Any] = {"command": sys.executable, "args": ["-m", "bilinc.cloud_mcp"]}
+    if not load_config_api_key():
+        # With a key saved by `bilinc login` the adapter reads it itself, so the
+        # client config carries no key at all. Without one, the client must pass it.
+        entry["env"] = {"BILINC_API_KEY": MCP_KEY_PLACEHOLDER}
+    return entry
+
+
 def _mcp_config() -> dict[str, Any]:
-    return {
-        "mcpServers": {
-            "bilinc": {
-                "command": "python",
-                "args": ["-m", "bilinc.cloud_mcp"],
-                "env": {"BILINC_API_KEY": "${BILINC_API_KEY}"},
-            }
-        }
-    }
+    return {"mcpServers": {"bilinc": _mcp_server_entry()}}
+
+
+def _claude_code_command() -> str:
+    argv = ["claude", "mcp", "add", "--scope", "user", "bilinc"]
+    if not load_config_api_key():
+        argv += ["-e", f"BILINC_API_KEY={MCP_KEY_PLACEHOLDER}"]
+    argv += ["--", sys.executable, "-m", "bilinc.cloud_mcp"]
+    return subprocess.list2cmdline(argv) if os.name == "nt" else shlex.join(argv)
+
+
+def _claude_desktop_config_path() -> str:
+    if sys.platform == "darwin":
+        return "~/Library/Application Support/Claude/claude_desktop_config.json"
+    if os.name == "nt":
+        return r"%APPDATA%\Claude\claude_desktop_config.json"
+    return "~/.config/Claude/claude_desktop_config.json"
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -174,7 +198,14 @@ def build_parser() -> argparse.ArgumentParser:
 
     mcp = sub.add_parser("mcp", help="Print hosted Cloud MCP adapter configuration")
     mcp_sub = mcp.add_subparsers(dest="mcp_command")
-    mcp_sub.add_parser("install", help="Print MCP config for agent runtimes")
+    mcp_install = mcp_sub.add_parser("install", help="Print MCP config for agent runtimes")
+    mcp_install.add_argument(
+        "--client",
+        choices=["json", "claude-code", "claude-desktop"],
+        default="json",
+        help="json: mcpServers config (default); claude-code: a `claude mcp add` command; "
+        "claude-desktop: the config plus where Claude Desktop keeps it",
+    )
 
     sub.add_parser("signup", help="Print the signup URL (free, no card required)")
 
@@ -252,7 +283,22 @@ def main(argv: list[str] | None = None) -> int:
         )
         return 0
     if args.command == "mcp" and args.mcp_command == "install":
-        _print(_mcp_config())
+        # stdout stays copy-paste clean; guidance goes to stderr.
+        if args.client == "claude-code":
+            print(_claude_code_command())
+        else:
+            _print(_mcp_config())
+        if args.client == "claude-desktop":
+            print(
+                f'Merge the "bilinc" entry into mcpServers in {_claude_desktop_config_path()}, '
+                "then restart Claude Desktop.",
+                file=sys.stderr,
+            )
+        if not load_config_api_key():
+            print(
+                f"No saved key yet: run `bilinc login` first, or replace {MCP_KEY_PLACEHOLDER} with your API key.",
+                file=sys.stderr,
+            )
         return 0
     if args.command is None:
         parser.print_help()

{bilinc-2.3.0 → bilinc-2.3.3}/src/bilinc/client.py

@@ -1,6 +1,6 @@
 """Bilinc Cloud client.
 
-Bilinc 2.3.0 is cloud-only: the PyPI package is a thin SDK and MCP adapter for
+Bilinc 2.3.3 is cloud-only: the PyPI package is a thin SDK and MCP adapter for
 https://bilinc.space. Local self-hosted StatePlane internals are no longer
 shipped in the public package.
 """
@@ -18,10 +18,10 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Callable
 
-__version__ = "2.3.0"
+__version__ = "2.3.3"
 DEFAULT_BASE_URL = "https://bilinc.space"
 SIGNUP_URL = "https://bilinc.space/signup"
-ACTIVATION_CAMPAIGN = "activation_2_3_0"
+ACTIVATION_CAMPAIGN = "activation_2_3_3"
 ACTIVATION_SIGNUP_URL = (
     f"{SIGNUP_URL}?utm_source=pypi&utm_medium=cli&utm_campaign={ACTIVATION_CAMPAIGN}"
 )

{bilinc-2.3.0 → bilinc-2.3.3/src/bilinc.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bilinc
-Version: 2.3.0
+Version: 2.3.3
 Summary: Cloud-only memory SDK and MCP adapter for autonomous agents
 Author: Bilinc Team
 License-Expression: BUSL-1.1
@@ -56,7 +56,7 @@ Dynamic: license-file
 
 Retrieval answers *"what is similar to this?"*. Long-running agents also need to answer *"who wrote this state, was it verified, did it contradict what we already knew, and can we undo it?"* — that is the layer Bilinc provides.
 
-Bilinc 2.3.0 on PyPI is the public cloud-only package: a thin Python SDK, CLI, and MCP adapter for Bilinc Cloud. It does not ship the local StatePlane, storage backends, eval, observability, integrations, or server runtime internals.
+Bilinc 2.3.3 on PyPI is the public cloud-only package: a thin Python SDK, CLI, and MCP adapter for Bilinc Cloud. It does not ship the local StatePlane, storage backends, eval, observability, integrations, or server runtime internals.
 
 > **Frozen regression receipt** — LongMemEval-s cleaned retrieval fixture, 500 questions: **Hit@5 98.0%**, **NDCG@5 0.913**, no LLM reranker, no paid API. This is an isolated retrieval guardrail, not a current hosted SLA, end-to-end agent score, or competitor ranking — see [Benchmark receipt](#benchmark-receipt) for the full scope and qualification.
 
@@ -93,13 +93,30 @@ The fastest path is `pip install -U bilinc`, `bilinc login`, then `bilinc quickt
 | --- | --- |
 | A hosted memory API for an agent or MCP client | The public cloud-only package from PyPI |
 | Local StatePlane, SQLite/PostgreSQL, benchmarks, or internals | This repository and the [architecture guide](docs/architecture.md) |
-| A hosted MCP connection | The [MCP setup guide](https://bilinc.space/docs/mcp) |
+| A hosted MCP connection without a Python install | The [remote MCP setup guide](https://bilinc.space/docs/remote-mcp) |
 
 The public package is intentionally smaller than this repository. It does not bundle the internal StatePlane or local
 storage runtime.
 
 ## Start in 60 Seconds
 
+### Claude connector, without installing Python
+
+Open **Customize → Connectors → Add custom connector** in Claude, name it Bilinc,
+and paste `https://mcp.bilinc.space/mcp`. Sign in and choose read-only or read and
+write access. The setup guide is [bilinc.space/mcp](https://bilinc.space/mcp).
+
+For the remote connector in Claude Code:
+
+```bash
+claude mcp add --transport http --scope user bilinc https://mcp.bilinc.space/mcp
+```
+
+Then run `/mcp` and authenticate. The remote connector has ten tools; the Python
+stdio adapter below has eight. Both connect to hosted Bilinc memory.
+
+### SDK and CLI
+
 ```bash
 pip install -U bilinc
 bilinc login
@@ -119,7 +136,7 @@ Cloud status check.
 To reproduce this release exactly:
 
 ```bash
-pip install -U bilinc==2.3.0
+pip install -U bilinc==2.3.3
 ```
 
 If you prefer a browser guide, open https://bilinc.space/install and follow the
@@ -131,18 +148,28 @@ Bilinc exposes a standard Model Context Protocol server over **stdio**, so any
 MCP-compatible client can connect — Claude Code, Codex, Cursor, Hermes-Agent,
 opencode, and others.
 
+After `bilinc login`, let the CLI write the setup for your client:
+
+```bash
+bilinc mcp install --client claude-code     # prints a ready `claude mcp add ...` command
+bilinc mcp install --client claude-desktop  # prints the config and where Claude Desktop keeps it
+bilinc mcp install                          # plain mcpServers JSON for any other client
+```
+
 ```json
 {
   "mcpServers": {
     "bilinc": {
-      "command": "python",
-      "args": ["-m", "bilinc.cloud_mcp"],
-      "env": { "BILINC_API_KEY": "bil_live_..." }
+      "command": "/path/to/python3",
+      "args": ["-m", "bilinc.cloud_mcp"]
     }
   }
 }
 ```
 
+`command` is the interpreter that has Bilinc installed, and the adapter reads the key saved by `bilinc login`, so
+the config carries no key. On a machine without a saved key, add `"env": { "BILINC_API_KEY": "bil_live_..." }`.
+
 Eight tools — the core memory lifecycle, and nothing else:
 
 | Tool | What it does |

{bilinc-2.3.0 → bilinc-2.3.3}/tests/test_cloud_only_package.py

@@ -12,9 +12,9 @@ import pytest
 def test_public_api_is_cloud_only():
     import bilinc
 
-    assert bilinc.__version__ == "2.3.0"
-    assert bilinc.version == "2.3.0"
-    assert "utm_campaign=activation_2_3_0" in bilinc.ACTIVATION_SIGNUP_URL
+    assert bilinc.__version__ == "2.3.3"
+    assert bilinc.version == "2.3.3"
+    assert "utm_campaign=activation_2_3_3" in bilinc.ACTIVATION_SIGNUP_URL
     assert hasattr(bilinc, "Bilinc")
     assert hasattr(bilinc, "CloudClient")
     assert not hasattr(bilinc, "StatePlane")
@@ -75,7 +75,7 @@ def test_cloud_client_normalizes_base_url():
     from bilinc import CloudClient
 
     transport = RecordingTransport({"status": "ok"})
-    client = CloudClient(api_key="bil_live_test", base_url="https://bilinc.space///", transport=transport)
+    client = CloudClient(api_key="bil_live_example", base_url="https://bilinc.space///", transport=transport)
 
     client.status()
 
@@ -87,7 +87,7 @@ def test_cloud_client_base_url_can_come_from_env(monkeypatch):
 
     monkeypatch.setenv("BILINC_BASE_URL", "http://127.0.0.1:9999/")
     transport = RecordingTransport({"status": "ok"})
-    client = CloudClient(api_key="bil_live_test", transport=transport)
+    client = CloudClient(api_key="bil_live_example", transport=transport)
 
     client.status()
 
@@ -98,7 +98,7 @@ def test_cloud_client_commit_posts_to_hosted_api():
     from bilinc import CloudClient
 
     transport = RecordingTransport({"success": True, "id": "mem_123"})
-    client = CloudClient(api_key="bil_live_test", base_url="https://bilinc.space", transport=transport)
+    client = CloudClient(api_key="bil_live_example", base_url="https://bilinc.space", transport=transport)
 
     result = client.commit("project.status", {"phase": "trial"}, memory_type="semantic", importance=0.8)
 
@@ -108,11 +108,11 @@ def test_cloud_client_commit_posts_to_hosted_api():
             "method": "POST",
             "url": "https://bilinc.space/api/cloud/memory/commit",
             "headers": {
-                "Authorization": "Bearer bil_live_test",
+                "Authorization": "Bearer bil_live_example",
                 "Content-Type": "application/json",
-                "User-Agent": "bilinc-python/2.3.0",
+                "User-Agent": "bilinc-python/2.3.3",
                 "X-Bilinc-Client": "python-sdk",
-                "X-Bilinc-Client-Version": "2.3.0",
+                "X-Bilinc-Client-Version": "2.3.3",
             },
             "body": json.dumps(
                 {
@@ -133,7 +133,7 @@ def test_cloud_client_recall_posts_to_hosted_api():
     from bilinc import CloudClient
 
     transport = RecordingTransport({"results": [{"key": "project.status"}]})
-    client = CloudClient(api_key="bil_live_test", transport=transport)
+    client = CloudClient(api_key="bil_live_example", transport=transport)
 
     result = client.recall("trial status", profile="balanced", limit=5)
 
@@ -148,7 +148,7 @@ def test_cloud_client_recall_forwards_point_in_time_timestamp():
     from bilinc import CloudClient
 
     transport = RecordingTransport({"results": []})
-    client = CloudClient(api_key="bil_live_test", transport=transport)
+    client = CloudClient(api_key="bil_live_example", transport=transport)
 
     client.recall(
         "deployment target",
@@ -167,7 +167,7 @@ def test_cloud_client_recall_forwards_point_in_time_timestamp():
 def test_cloud_client_rejects_an_unbounded_point_in_time_timestamp():
     from bilinc import BilincValidationError, CloudClient
 
-    client = CloudClient(api_key="bil_live_test", transport=RecordingTransport({}))
+    client = CloudClient(api_key="bil_live_example", transport=RecordingTransport({}))
 
     with pytest.raises(BilincValidationError, match="query_timestamp"):
         client.recall("q", query_timestamp="x" * 65)
@@ -177,7 +177,7 @@ def test_cloud_client_status_reads_the_authenticated_status_endpoint():
     from bilinc import CloudClient
 
     transport = RecordingTransport({"status": "ok", "plan": {"key": "pro"}})
-    client = CloudClient(api_key="bil_live_test", transport=transport)
+    client = CloudClient(api_key="bil_live_example", transport=transport)
 
     result = client.status()
 
@@ -187,8 +187,8 @@ def test_cloud_client_status_reads_the_authenticated_status_endpoint():
             "method": "GET",
             "url": "https://bilinc.space/api/cloud/status",
             "headers": {
-                "Authorization": "Bearer bil_live_test",
-                "User-Agent": "bilinc-python/2.3.0",
+                "Authorization": "Bearer bil_live_example",
+                "User-Agent": "bilinc-python/2.3.3",
             },
             "body": None,
             "timeout": 30.0,
@@ -200,7 +200,7 @@ def test_cloud_client_health_stays_on_the_public_service_endpoint():
     from bilinc import CloudClient
 
     transport = RecordingTransport({"status": "ok", "mode": "live_cloud"})
-    client = CloudClient(api_key="bil_live_test", transport=transport)
+    client = CloudClient(api_key="bil_live_example", transport=transport)
 
     result = client.health()
 
@@ -261,7 +261,7 @@ def test_cli_signup_and_missing_key_failure(monkeypatch, capsys):
     assert main(["signup"]) == 0
     signup_out = capsys.readouterr()
     assert "https://bilinc.space/signup" in signup_out.out
-    assert "activation_2_3_0" in signup_out.out
+    assert "activation_2_3_3" in signup_out.out
     assert "quicktest" in signup_out.out
 
     assert main(["commit", "--key", "smoke_key", "--value", "hello"]) == 1
@@ -305,7 +305,7 @@ def test_cli_start_login_doctor_quicktest_and_mcp_config(monkeypatch, capsys, tm
     assert "bilinc login --api-key <key>" in start_out.out
     assert "bilinc quicktest" in start_out.out
     assert "install_guide" in start_out.out
-    assert "activation_2_3_0" in start_out.out
+    assert "activation_2_3_3" in start_out.out
 
     assert cli_main.main(["login", "--api-key", "bil_live_cli_test"]) == 0
     login_out = capsys.readouterr()
@@ -327,6 +327,56 @@ def test_cli_start_login_doctor_quicktest_and_mcp_config(monkeypatch, capsys, tm
     assert "bil_live_cli_test" not in mcp_out.out
 
 
+def test_mcp_install_uses_the_login_key_and_a_real_interpreter(monkeypatch, capsys, tmp_path):
+    import sys
+
+    from bilinc.cli import main as cli_main
+
+    monkeypatch.delenv("BILINC_API_KEY", raising=False)
+    monkeypatch.setenv("BILINC_CONFIG_DIR", str(tmp_path))
+    assert cli_main.main(["login", "--api-key", "bil_live_saved_key"]) == 0
+    capsys.readouterr()
+
+    # Default JSON: absolute interpreter, and no env block — the adapter reads the saved key.
+    assert cli_main.main(["mcp", "install"]) == 0
+    out = capsys.readouterr()
+    server = json.loads(out.out)["mcpServers"]["bilinc"]
+    assert server == {"command": sys.executable, "args": ["-m", "bilinc.cloud_mcp"]}
+    assert "bil_live_saved_key" not in out.out + out.err
+    assert "${BILINC_API_KEY}" not in out.out
+
+    # Claude Code: one runnable command, user scope, no key on the command line.
+    assert cli_main.main(["mcp", "install", "--client", "claude-code"]) == 0
+    out = capsys.readouterr()
+    assert out.out.startswith("claude mcp add --scope user bilinc -- ")
+    assert out.out.rstrip().endswith("-m bilinc.cloud_mcp")
+    assert "BILINC_API_KEY" not in out.out
+    assert "bil_live_saved_key" not in out.out + out.err
+
+    # Claude Desktop: clean JSON on stdout, the config location on stderr.
+    assert cli_main.main(["mcp", "install", "--client", "claude-desktop"]) == 0
+    out = capsys.readouterr()
+    assert json.loads(out.out)["mcpServers"]["bilinc"]["command"] == sys.executable
+    assert "claude_desktop_config.json" in out.err
+    assert "bil_live_saved_key" not in out.out + out.err
+
+
+def test_mcp_install_without_a_saved_key_asks_for_one(monkeypatch, capsys, tmp_path):
+    from bilinc.cli import main as cli_main
+
+    monkeypatch.delenv("BILINC_API_KEY", raising=False)
+    monkeypatch.setenv("BILINC_CONFIG_DIR", str(tmp_path))
+
+    assert cli_main.main(["mcp", "install"]) == 0
+    out = capsys.readouterr()
+    assert json.loads(out.out)["mcpServers"]["bilinc"]["env"] == {"BILINC_API_KEY": "bil_live_..."}
+    assert "bilinc login" in out.err
+
+    assert cli_main.main(["mcp", "install", "--client", "claude-code"]) == 0
+    out = capsys.readouterr()
+    assert "-e BILINC_API_KEY=bil_live_..." in out.out
+
+
 def _forbidden_package_prefixes(root: str = "") -> tuple[str, ...]:
     return tuple(
         f"{root}{prefix}"