@zvndev/circular-mcp 0.1.2 → 0.1.4

package/README.md

@@ -72,9 +72,10 @@ Steps come in three kinds:
 - **ACTION**: you do it, then tick it with `circular_complete_step` and real
   evidence in `proof` (test output, a diff summary, a link).
 - **REVIEW**: a human gate. `circular_complete_step` answers **403** for these,
-  always: an agent may never sign off its own review. While the process review
-  gate is parked, open REVIEW steps do not block `done`; leave them unticked and
-  post proof/commentary instead.
+  always: an agent may never sign off its own review. Enrolled runner connections
+  cannot mark done with open stored REVIEW or AUTOMATION steps, even when paused.
+  Legacy callers retain the configured legacy process-gate policy (currently
+  off); an unticked review is never an agent approval. Post proof/commentary.
 - **AUTOMATION**: ticked by its own CI/GitHub signal, not by hand.
 
 `circular_get_next_work` deliberately **does not reserve** the issue it returns.
@@ -82,11 +83,51 @@ Reservations live in `circular_claim_issue_work`, keyed by a stable request id
 for safe retry after a lost response. Several candidates come back so two agents
 pulling at the same moment can pick another candidate if a reservation loses.
 
+## MCP tools versus an always-on computer
+
+Adding this stdio connector makes tools available to an agent. It does not
+start a provider, register a worker, or install a background service. Circular's
+cloud durably queues assignments, mentions and workflow events. An explicitly
+enrolled **foreground local runner** polls its addressed deliveries and launches
+the installed Codex or Claude CLI on that computer, one job at a time. Its
+connection and provider subscription stay private to that computer.
+
+Use the [public connection docs](https://gocircular.dev/docs) after
+browser login (or importing an admin-created workspace-agent connection), linking
+the project repository, and connecting the local checkout. Keep `circular runner
+start --connection CONNECTION_ID` running; an OS service is a separate explicit
+operator setup, never an automatic side effect of installing MCP or Desktop.
+
+`runner register --allow-circular-tools` explicitly permits unattended use of
+the runner's generated Circular MCP tools. `--allow-write` separately permits
+local code edits within the grant/profile ceiling. Neither flag grants access
+to unrelated MCP servers or lets an agent approve human-only steps. A runner
+works its already leased delivery rather than pulling unrelated `next-work`
+candidates. Registration requires the explicit Circular tool opt-in to avoid
+provider approval prompts stranding headless work. Use an interactive agent if
+you do not want unattended tool calls.
+
 ## Authentication
 
-Identical to the CLI. Provide a **team API key** (`circ_tk_…`) plus the
-workspace and team ids, via environment variables (MCP clients inject these
-through the server's `env` block):
+Identical to the CLI. The normal path is managed browser sign-in:
+
+```bash
+npx -y @zvndev/circular-cli login --runtime codex
+```
+
+That command opens Circular, asks the signed-in human to approve a named agent,
+then stores the managed connection locally in `~/.circular/connections.json`.
+No API key has to be copied into an agent prompt or MCP config.
+
+For long-running MCP processes, pin the connection id returned by `login`:
+
+```
+CIRCULAR_CONNECTION_ID=key_or_connection_id_from_login
+```
+
+Owners/admins can still provide an explicit **team API key** (`circ_tk_…`) for
+ongoing workspace agents or legacy automation. MCP clients inject these through
+the server's `env` block:
 
 ```
 CIRCULAR_API_KEY=circ_tk_xxx
@@ -95,7 +136,9 @@ CIRCULAR_TEAM_ID=team_xxx
 CIRCULAR_BASE_URL=https://gocircular.dev   # optional; default
 ```
 
-`~/.circular/config.json` also works as a fallback.
+`~/.circular/config.json` also works as a fallback for explicit keys. An
+explicit key always wins over managed login; a Desktop-bound agent identity does
+not borrow a managed or global fallback credential.
 
 ### Minting a team API key
 
@@ -113,9 +156,7 @@ below with `node /ABS/PATH/mcp/bin/circular-mcp.mjs`.
 
 ```bash
 claude mcp add circular \
-  -e CIRCULAR_API_KEY=circ_tk_xxx \
-  -e CIRCULAR_WORKSPACE_ID=ws_xxx \
-  -e CIRCULAR_TEAM_ID=team_xxx \
+  -e CIRCULAR_CONNECTION_ID=key_or_connection_id_from_login \
   -- npx -y @zvndev/circular-mcp
 ```
 
@@ -131,9 +172,7 @@ Via the CLI:
 
 ```bash
 codex mcp add circular \
-  --env CIRCULAR_API_KEY=circ_tk_xxx \
-  --env CIRCULAR_WORKSPACE_ID=ws_xxx \
-  --env CIRCULAR_TEAM_ID=team_xxx \
+  --env CIRCULAR_CONNECTION_ID=key_or_connection_id_from_login \
   -- npx -y @zvndev/circular-mcp
 ```
 
@@ -146,6 +185,12 @@ args = ["-y", "@zvndev/circular-mcp"]
 env = { CIRCULAR_API_KEY = "circ_tk_xxx", CIRCULAR_WORKSPACE_ID = "ws_xxx", CIRCULAR_TEAM_ID = "team_xxx" }
 ```
 
+For a managed connection, use:
+
+```toml
+env = { CIRCULAR_CONNECTION_ID = "key_or_connection_id_from_login" }
+```
+
 Verify with `codex mcp list` / `codex mcp get circular`.
 
 ### Cursor

package/bin/circular-mcp.mjs

@@ -10,10 +10,10 @@
  * Transport: MCP stdio (newline-delimited JSON-RPC 2.0). Protocol messages go on
  * stdin/stdout; everything human-facing goes to stderr.
  *
- * Auth is identical to the CLI: CIRCULAR_API_KEY (a team key, circ_tk_…),
- * CIRCULAR_WORKSPACE_ID, CIRCULAR_TEAM_ID (and optional CIRCULAR_BASE_URL), or
- * ~/.circular/config.json. MCP clients typically inject these via the server's
- * env block (e.g. `claude mcp add ... -e CIRCULAR_API_KEY=…`).
+ * Auth is identical to the CLI: a managed browser login from
+ * ~/.circular/connections.json, optionally pinned with CIRCULAR_CONNECTION_ID,
+ * or an explicit CIRCULAR_API_KEY plus workspace/team ids for legacy/service
+ * agents.
  */
 import { loadConfig } from "../lib/vendor/config.mjs";
 import { dispatch, SERVER_INFO } from "../lib/server.mjs";

package/lib/server.mjs

@@ -21,18 +21,20 @@ const SUPPORTED_PROTOCOL_VERSIONS = new Set([
   "2024-11-05",
 ]);
 
-export const SERVER_INFO = { name: "circular-mcp", version: "0.1.2" };
+export const SERVER_INFO = { name: "circular-mcp", version: "0.1.4" };
 
 /**
  * The briefing every client sees on connect. This is the only onboarding an
  * agent gets before it starts calling tools, so it states the model (pull-based,
- * Circular never executes anything), the loop, and the two absolute rules.
+ * cloud coordination versus explicitly enrolled local execution), the loop,
+ * and the two absolute rules.
  */
 export const INSTRUCTIONS = [
-  "Circular is the source of truth for planning and task management. Circular is the brain; your agent is the hands. It never runs your agent and never executes work: you pull work, do it on your own machine, and write the result back.",
-  "Work is PULLED, never pushed. Call circular_get_next_work to find out what to do and whether you are allowed to do it, and read each candidate's `situation.disposition` before acting. Only `ready_for_you` and `no_process` are yours to pick up.",
+  "Circular is the source of truth for planning and task management. Its cloud queues work and stores context and proof; it does not host agent execution or sell inference. Interactive agents pull work themselves. A separately enrolled foreground runner polls addressed deliveries and starts the installed Codex or Claude CLI on its own computer, using that computer's private, scoped connection and provider subscription.",
+  "MCP supplies tools; adding this connector does not start a worker or install an OS service. For interactive work, call circular_get_next_work and read each candidate's `situation.disposition`; only `ready_for_you` and `no_process` are yours to pick up. An enrolled runner already owns a specific delivery: stay on that task instead of pulling or claiming unrelated candidates.",
   AGENT_LOOP_SUMMARY,
-  "Two rules are absolute. First, an API key can NEVER complete a REVIEW step; review is the human sign-off, refused for every api_key caller including the agent that did the work. Leave REVIEW steps unticked: they no longer hold the issue open, so do the ACTION steps, record your proof, and close the issue when the work is done. Second, never invent, reorder, or edit the step ladder; it comes from the team's Process. Record proof on the step it belongs to with circular_complete_step, using the stepId exactly as returned.",
+  "Two rules are absolute. First, an API key can NEVER complete a REVIEW step; review is the human sign-off, refused for every api_key caller including the agent that did the work. Enrolled runner agents cannot mark done while stored REVIEW or AUTOMATION steps remain open or unreadable, even when their computer is paused and the legacy process gate is disabled. Legacy callers still follow the server's configured completion policy; do not assume an open review always blocks them or that they may approve it. Post proof and leave human-only steps unticked. Second, never invent, reorder, or edit the step ladder; it comes from the team's Process. Record proof on the step it belongs to with circular_complete_step, using the stepId exactly as returned.",
+  "Runner opt-ins are separate: --allow-write permits local repository edits within the grant/profile ceiling; registration requires --allow-circular-tools to explicitly permit unattended use of the generated Circular MCP tools. Neither flag authorizes another account, repository, unrelated MCP server or human approval. A runner handles one job at a time and no background service is installed automatically.",
   "Do not create local Markdown TODO, PLAN, status, or handoff files as a parallel tracker. Use circular_plan_tasks for plans and circular_comment_issue for updates, handoffs, and narrative proof. Markdown is only for durable product documentation or an artifact the user explicitly requested.",
 ].join(" ");
 

package/lib/tools.mjs

@@ -30,7 +30,9 @@ export const AGENT_LOOP_SUMMARY =
   "(6) circular_complete_step with real proof for each ACTION step you finish, " +
   "(7) circular_comment_issue for the narrative handoff, " +
   "(8) circular_release_issue_work_claim when you stop holding the lane, " +
-  "(9) circular_update_issue to done once the work is finished.";
+  "(9) circular_update_issue to done only when the server's completion policy permits it; " +
+  "enrolled runner agents must wait for stored human REVIEW and AUTOMATION gates. " +
+  "This candidate-pull loop is for interactive agents; a runner stays on its already leased delivery.";
 
 /** Drop undefined keys so we never send `"priority": undefined`. */
 function prune(obj) {
@@ -109,8 +111,8 @@ export const TOOLS = [
   {
     name: "circular_get_next_work",
     description:
-      "THE pull primitive: ask Circular what to work on. Circular never pushes work to you and never " +
-      "runs your agent, so this is how work reaches you. " +
+      "The interactive pull primitive: ask Circular what to work on. An enrolled local runner " +
+      "instead polls addressed deliveries and starts its installed provider; it must stay on its leased task. " +
       "WHEN: at the start of every work cycle, and again after you finish an issue. " +
       "RETURNS: `actor` (who Circular thinks you are, including `canCompleteReviewSteps`), `limit`, " +
       "and `candidates`, highest priority first, with done, cancelled and blocked issues already " +
@@ -119,13 +121,14 @@ export const TOOLS = [
       "READ `situation.disposition` BEFORE ACTING. It is one of: " +
       "`ready_for_you` (the current step is an open ACTION step you may complete: proceed), " +
       "`waiting_on_human_review` (the current step is a REVIEW step no API key can tick: leave it " +
-      "unticked, but it does not block the issue, so finish the work and close it), " +
+      "unticked and post a handoff; enrolled runner agents cannot close it before human review), " +
       "`waiting_on_automation` (an AUTOMATION step, ticked by its own signal, not by you: skip it), " +
       "`assigned_to_someone_else` (the current step names another person, team, or agent: skip it), " +
       "`process_complete` (every step ticked; it only needs closing), " +
       "`no_process` (no ladder: do the work, comment, set it to done), " +
       "`ladder_unreadable` (the stored steps cannot be parsed, so Circular refuses step edits on " +
-      "this issue: do not try to repair the ladder, but the issue can still be closed). " +
+      "this issue: do not try to repair the ladder; enrolled runner agents cannot close it, " +
+      "while legacy callers follow the configured completion policy). " +
       "`situation.currentStep` gives the open step's id, kind, `assignment`, `assignedTo`, " +
       "`canComplete`, and a `refusal` reason when you may not complete it. " +
       "IT DOES NOT RESERVE the issue: several agents can be handed the same candidate. Reserve by " +
@@ -287,15 +290,15 @@ export const TOOLS = [
     name: "circular_update_issue",
     description:
       "Update an issue's status, priority, title, description, or assignee. This is also how you " +
-      "CLAIM work: set " +
-      "status to in_progress the moment you pick a candidate up, because circular_get_next_work does " +
-      "not claim and another agent may be holding the same one. " +
+      "record progress, not reserve work: use circular_claim_issue_work for an interactive claim, " +
+      "then set status to in_progress. circular_get_next_work does not claim; a runner already holds its addressed delivery. " +
       "WHEN: in_progress on pickup; done once the whole ladder is finished. " +
       "REFUSES with 409: moving to done while any blocking issue is still open. That is the " +
       "dependency graph working, not an obstacle to route around: post your proof, leave a comment, " +
       "and pick up something that is not blocked. " +
-      "An open REVIEW step no longer refuses done. It stays unticked, because no API key may " +
-      "complete one, but it does not hold the issue open. " +
+      "Enrolled runner agents also receive 409 for open stored REVIEW or AUTOMATION steps or an unreadable ladder, " +
+      "even if their computer is paused. Legacy callers follow PROCESS_REVIEW_GATE_ENABLED, currently off; " +
+      "an open REVIEW step alone does not block those callers while that legacy gate is off. No API key may complete a REVIEW step. " +
       "Setting status to cancelled is never gated, because abandoning work must always be possible. " +
       "Returns the updated issue.",
     inputSchema: {

package/lib/vendor/client.mjs

@@ -1,28 +1,12 @@
-/**
- * VENDORED from cli/lib/client.mjs. Do not edit here.
- *
- * The MCP server is published as a standalone package and advertises itself as
- * dependency-free, which is the whole point of `npx -y @zvndev/circular-mcp`:
- * nothing to resolve, nothing to install. It used to import this straight out
- * of `../../cli/lib`, a path that exists in the repo and in no published
- * tarball, so `npm publish` would have produced a package that crashed on its
- * first import.
- *
- * Everything below this header is a byte-for-byte copy of the CLI's file, and
- * test/package.test.mjs fails if the two ever drift.
- */
-
-/**
- * Thin HTTP client for the Circular Agent API. Authenticates with the team API
- * key via the Authorization: Bearer header. Returns parsed JSON; throws an
- * ApiError (with status + body) on non-2xx so the CLI can print + exit non-zero.
- */
 /**
  * Thin HTTP client for the Circular Agent API. Authenticates with the team API
  * key via the Authorization: Bearer header. Returns parsed JSON; throws an
  * ApiError (with status + body) on non-2xx so the CLI can print + exit non-zero.
  */
 import { readConfigFile } from "./config.mjs";
+import { readConnectionsFile, selectConnection } from "./connections.mjs";
+const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
+
 export class ApiError extends Error {
   constructor(message, status, body) {
     super(message);
@@ -33,12 +17,18 @@ export class ApiError extends Error {
 }
 
 export function teamBase(config) {
-  if (!config.apiKey) throw new Error("Missing API key. Set CIRCULAR_API_KEY.");
+  if (!config.apiKey) throw new Error("Not signed in. Run `circular login` or set CIRCULAR_API_KEY.");
   if (!config.workspaceId) throw new Error("Missing workspace. Set CIRCULAR_WORKSPACE_ID or --workspace.");
   if (!config.teamId) throw new Error("Missing team. Set CIRCULAR_TEAM_ID or --team.");
   return `${config.baseUrl}/api/workspaces/${config.workspaceId}/teams/${config.teamId}`;
 }
 
+export function workspaceBase(config) {
+  if (!config.apiKey) throw new Error("Not signed in. Run `circular login` or set CIRCULAR_API_KEY.");
+  if (!config.workspaceId) throw new Error("Missing workspace. Set CIRCULAR_WORKSPACE_ID or --workspace.");
+  return `${config.baseUrl}/api/workspaces/${config.workspaceId}`;
+}
+
 /**
  * The key on disk, if it is not the one that was just refused.
  *
@@ -68,14 +58,45 @@ function rotatedKey(usedKey, readFile = readConfigFile) {
 }
 
 async function send(config, method, url, body) {
-  return fetch(url, {
-    method,
-    headers: {
-      Authorization: `Bearer ${config.apiKey}`,
-      ...(body ? { "Content-Type": "application/json" } : {}),
-    },
-    ...(body ? { body: JSON.stringify(body) } : {}),
-  });
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), config.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
+  try {
+    return await fetch(url, {
+      method,
+      redirect: "manual",
+      signal: controller.signal,
+      headers: {
+        Authorization: `Bearer ${config.apiKey}`,
+        ...(body ? { "Content-Type": "application/json" } : {}),
+      },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function refreshManagedConnection(config, readStore = readConnectionsFile) {
+  if (!config.managedConnectionId) return config;
+  const store = readStore();
+  const connection = selectConnection(store, config.managedConnectionId);
+  if (!connection) {
+    throw new Error(`Circular connection ${config.managedConnectionId} is not saved locally. The MCP process is pinned to this connection and will not fall back to another account.`);
+  }
+  if (stripTrailingSlash(connection.baseUrl) !== stripTrailingSlash(config.baseUrl)) {
+    throw new Error(`Circular connection ${config.managedConnectionId} no longer matches the pinned API origin.`);
+  }
+  if (connection.workspaceId !== config.workspaceId) {
+    throw new Error(`Circular connection ${config.managedConnectionId} no longer matches the pinned workspace.`);
+  }
+  if (config.agentParticipantId && connection.agentParticipantId !== config.agentParticipantId) {
+    throw new Error(`Circular connection ${config.managedConnectionId} no longer matches the pinned agent identity.`);
+  }
+  if (config.authorizingUserId && connection.authorizingUserId !== config.authorizingUserId) {
+    throw new Error(`Circular connection ${config.managedConnectionId} no longer matches the pinned authorizing user.`);
+  }
+  config.apiKey = connection.token;
+  return config;
 }
 
 /**
@@ -89,7 +110,9 @@ export async function apiRequest(
   path,
   { query, body } = {},
   readFile = readConfigFile,
+  readConnectionStore = readConnectionsFile,
 ) {
+  refreshManagedConnection(config, readConnectionStore);
   const url = new URL(`${teamBase(config)}${path}`);
   if (query) {
     for (const [key, value] of Object.entries(query)) {
@@ -105,7 +128,7 @@ export async function apiRequest(
   // The config object is mutated so the session uses the live key afterward:
   // recovering one request and leaving the next twenty to fail would be worse
   // than not recovering at all, because the failure would look intermittent.
-  if (response.status === 401 && !config.agentParticipantId) {
+  if (response.status === 401 && !config.agentParticipantId && !config.managedConnectionId) {
     const rotated = rotatedKey(config.apiKey, readFile);
     if (rotated) {
       config.apiKey = rotated;
@@ -129,6 +152,13 @@ export async function apiRequest(
         parsed,
       );
     }
+    if (response.status === 401 && config.managedConnectionId) {
+      throw new ApiError(
+        `${method} ${path} failed (401): This managed Circular connection expired or was revoked. Run \`circular login\` again and update CIRCULAR_CONNECTION_ID to the new connection id; no fallback API key was used.`,
+        response.status,
+        parsed,
+      );
+    }
     const detail =
       parsed && typeof parsed === "object" && parsed.error ? parsed.error : response.statusText;
     throw new ApiError(`${method} ${path} failed (${response.status}): ${detail}`, response.status, parsed);
@@ -136,3 +166,63 @@ export async function apiRequest(
 
   return parsed;
 }
+
+export async function workspaceRequest(
+  config,
+  method,
+  path,
+  { query, body } = {},
+  readFile = readConfigFile,
+  readConnectionStore = readConnectionsFile,
+) {
+  refreshManagedConnection(config, readConnectionStore);
+  const url = new URL(`${workspaceBase(config)}${path}`);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
+    }
+  }
+
+  let response = await send(config, method, url, body);
+  if (response.status === 401 && !config.agentParticipantId && !config.managedConnectionId) {
+    const rotated = rotatedKey(config.apiKey, readFile);
+    if (rotated) {
+      config.apiKey = rotated;
+      response = await send(config, method, url, body);
+    }
+  }
+
+  const text = await response.text();
+  let parsed;
+  try {
+    parsed = text ? JSON.parse(text) : null;
+  } catch {
+    parsed = text;
+  }
+
+  if (!response.ok) {
+    if (response.status === 401 && config.agentParticipantId) {
+      throw new ApiError(
+        `${method} ${path} failed (401): This agent session credential expired or was revoked. Reconnect the session in Circular to authorize the same agent again; the global account key was not used.`,
+        response.status,
+        parsed,
+      );
+    }
+    if (response.status === 401 && config.managedConnectionId) {
+      throw new ApiError(
+        `${method} ${path} failed (401): This managed Circular connection expired or was revoked. Run \`circular login\` again and update CIRCULAR_CONNECTION_ID to the new connection id; no fallback API key was used.`,
+        response.status,
+        parsed,
+      );
+    }
+    const detail =
+      parsed && typeof parsed === "object" && parsed.error ? parsed.error : response.statusText;
+    throw new ApiError(`${method} ${path} failed (${response.status}): ${detail}`, response.status, parsed);
+  }
+
+  return parsed;
+}
+
+function stripTrailingSlash(url) {
+  return typeof url === "string" ? url.replace(/\/+$/, "") : url;
+}

package/lib/vendor/config.mjs

@@ -1,17 +1,3 @@
-/**
- * VENDORED from cli/lib/config.mjs. Do not edit here.
- *
- * The MCP server is published as a standalone package and advertises itself as
- * dependency-free, which is the whole point of `npx -y @zvndev/circular-mcp`:
- * nothing to resolve, nothing to install. It used to import this straight out
- * of `../../cli/lib`, a path that exists in the repo and in no published
- * tarball, so `npm publish` would have produced a package that crashed on its
- * first import.
- *
- * Everything below this header is a byte-for-byte copy of the CLI's file, and
- * test/package.test.mjs fails if the two ever drift.
- */
-
 /**
  * Config resolution for the Circular CLI.
  *
@@ -22,6 +8,7 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { findConnection, hasConnectionId, readConnectionsFile, tryReadConnectionsFile } from "./connections.mjs";
 
 export const DEFAULT_BASE_URL = "https://gocircular.dev";
 
@@ -41,7 +28,7 @@ export function readConfigFile(path = configFilePath()) {
  * Merge flags, env, and file into the effective config. `flags` are the parsed
  * CLI flags; `env` defaults to process.env; `file` is the parsed config file.
  */
-export function resolveConfig(flags = {}, env = process.env, file = {}) {
+export function resolveConfig(flags = {}, env = process.env, file = {}, connectionStore = {}) {
   const agentParticipantId = env.CIRCULAR_AGENT_PARTICIPANT_ID?.trim();
   const authorizingUserId = env.CIRCULAR_AUTHORIZING_USER_ID?.trim();
   const pick = (flagKey, envKey, fileKey, fallback) => {
@@ -51,21 +38,85 @@ export function resolveConfig(flags = {}, env = process.env, file = {}) {
     return fallback;
   };
 
+  const explicitRuntimeApiKey = flags["api-key"] !== undefined && flags["api-key"] !== true
+    ? flags["api-key"]
+    : env.CIRCULAR_API_KEY || undefined;
+  const legacyFileApiKey = !agentParticipantId ? file.apiKey : undefined;
+  const requestedBaseUrlOverride = flags["base-url"] !== undefined && flags["base-url"] !== true
+    ? flags["base-url"]
+    : env.CIRCULAR_BASE_URL || undefined;
+  const requestedWorkspaceOverride = flags.workspace !== undefined && flags.workspace !== true
+    ? flags.workspace
+    : env.CIRCULAR_WORKSPACE_ID || undefined;
+  const requestedTeamOverride = flags.team !== undefined && flags.team !== true
+    ? flags.team
+    : env.CIRCULAR_TEAM_ID || undefined;
+  const requestedBaseUrl = stripTrailingSlash(
+    pick("base-url", "CIRCULAR_BASE_URL", "baseUrl", undefined)
+  );
+  const requestedWorkspaceId = pick("workspace", "CIRCULAR_WORKSPACE_ID", "workspaceId", undefined);
+  const requestedTeamId = pick("team", "CIRCULAR_TEAM_ID", "teamId", undefined);
+  const connectionId = flags.connection !== undefined && flags.connection !== true
+    ? flags.connection
+    : env.CIRCULAR_CONNECTION_ID || file.connectionId || undefined;
+  const managedConnection = !explicitRuntimeApiKey && !agentParticipantId
+    ? findConnection(connectionStore, {
+      id: connectionId,
+      baseUrl: stripTrailingSlash(requestedBaseUrlOverride),
+      workspaceId: requestedWorkspaceOverride,
+    })
+    : null;
+
+  const hasManagedConnectionFilter = Boolean(requestedBaseUrlOverride || requestedWorkspaceOverride);
+  const hasSavedConnections = Array.isArray(connectionStore?.connections) && connectionStore.connections.length > 0;
+  if ((connectionId || (hasManagedConnectionFilter && hasSavedConnections)) && !managedConnection && !explicitRuntimeApiKey && !agentParticipantId) {
+    if (!connectionId) {
+      throw new Error("No saved Circular connection matches the requested origin/workspace/team. Run circular status or circular login.");
+    }
+    const reason = hasConnectionId(connectionStore, connectionId)
+      ? "but it does not match the requested origin/workspace/team"
+      : "and it is not saved locally";
+    throw new Error(`Circular connection ${connectionId} was requested ${reason}. Run circular status or circular login.`);
+  }
+
+  if (managedConnection) {
+    return {
+      apiKey: managedConnection.token,
+      baseUrl: stripTrailingSlash(managedConnection.baseUrl),
+      workspaceId: managedConnection.workspaceId,
+      teamId: requestedTeamOverride ?? managedConnection.teamId,
+      managedConnectionId: managedConnection.id,
+      ...(managedConnection.agentParticipantId ? { agentParticipantId: managedConnection.agentParticipantId } : {}),
+      ...(managedConnection.authorizingUserId ? { authorizingUserId: managedConnection.authorizingUserId } : {}),
+    };
+  }
+
   return {
     // A bound session cannot borrow the operator's global credential, including
     // when its delegated key is missing rather than rejected by the server.
-    apiKey: pick("api-key", "CIRCULAR_API_KEY", "apiKey", undefined),
+    apiKey: explicitRuntimeApiKey ?? legacyFileApiKey,
     baseUrl: stripTrailingSlash(
       pick("base-url", "CIRCULAR_BASE_URL", "baseUrl", DEFAULT_BASE_URL)
     ),
-    workspaceId: pick("workspace", "CIRCULAR_WORKSPACE_ID", "workspaceId", undefined),
-    teamId: pick("team", "CIRCULAR_TEAM_ID", "teamId", undefined),
+    workspaceId: requestedWorkspaceId,
+    teamId: requestedTeamId,
     ...(agentParticipantId ? { agentParticipantId, ...(authorizingUserId ? { authorizingUserId } : {}) } : {}),
   };
 }
 
-export function loadConfig(flags = {}) {
-  return resolveConfig(flags, process.env, readConfigFile());
+export function loadConfig(flags = {}, options = {}) {
+  const file = readConfigFile();
+  if (options.allowMissingManagedConnection) {
+    return resolveConfig(flags, process.env, file, { version: 1, currentConnectionId: null, connections: [] });
+  }
+  const hasExplicitRuntimeApiKey = flags["api-key"] !== undefined && flags["api-key"] !== true
+    ? true
+    : Boolean(process.env.CIRCULAR_API_KEY);
+  const hasBoundDesktopIdentity = Boolean(process.env.CIRCULAR_AGENT_PARTICIPANT_ID?.trim());
+  const connectionStore = hasExplicitRuntimeApiKey || hasBoundDesktopIdentity
+    ? tryReadConnectionsFile()
+    : readConnectionsFile();
+  return resolveConfig(flags, process.env, file, connectionStore);
 }
 
 function stripTrailingSlash(url) {

package/lib/vendor/connections.mjs

@@ -0,0 +1,149 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export function connectionsFilePath() {
+  if (process.env.CIRCULAR_CONNECTIONS_FILE) return process.env.CIRCULAR_CONNECTIONS_FILE;
+  return join(homedir(), ".circular", "connections.json");
+}
+
+export function isTrustedCircularOrigin(value) {
+  try {
+    const url = new URL(value);
+    if (url.protocol === "https:") return true;
+    return url.protocol === "http:" && ["localhost", "127.0.0.1", "::1"].includes(url.hostname);
+  } catch {
+    return false;
+  }
+}
+
+export function readConnectionsFile(path = connectionsFilePath()) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return normalizeStore({});
+    }
+    throw new Error(`Could not read Circular connections file at ${path}. Fix or move the corrupt file before writing a new managed connection.`);
+  }
+  assertValidStore(parsed, path);
+  return normalizeStore(parsed);
+}
+
+export function tryReadConnectionsFile(path = connectionsFilePath()) {
+  try {
+    return readConnectionsFile(path);
+  } catch {
+    return normalizeStore({});
+  }
+}
+
+export function writeConnectionsFile(store, path = connectionsFilePath()) {
+  assertValidStore(store, path);
+  const normalized = normalizeStore(store);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(normalized, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, path);
+  try {
+    chmodSync(path, 0o600);
+  } catch {
+    // Best effort on non-POSIX filesystems.
+  }
+  return normalized;
+}
+
+export function normalizeStore(store) {
+  const connections = Array.isArray(store?.connections)
+    ? store.connections.filter(isConnection)
+    : [];
+  const currentConnectionId = typeof store?.currentConnectionId === "string"
+    && connections.some((connection) => connection.id === store.currentConnectionId)
+    ? store.currentConnectionId
+    : null;
+  return { version: 1, currentConnectionId, connections };
+}
+
+export function selectConnection(store, id) {
+  const normalized = normalizeStore(store);
+  const connectionId = id || normalized.currentConnectionId;
+  if (!connectionId) return null;
+  return normalized.connections.find((connection) => connection.id === connectionId) ?? null;
+}
+
+export function findConnection(store, { id, baseUrl, workspaceId, teamId } = {}) {
+  const normalized = normalizeStore(store);
+  const candidates = id
+    ? normalized.connections.filter((connection) => connection.id === id)
+    : normalized.connections.filter((connection) => connection.id === normalized.currentConnectionId);
+  return candidates.find((connection) =>
+    (!baseUrl || stripTrailingSlash(connection.baseUrl) === stripTrailingSlash(baseUrl)) &&
+    (!workspaceId || connection.workspaceId === workspaceId) &&
+    (!teamId || connection.teamId === teamId)
+  ) ?? null;
+}
+
+export function hasConnectionId(store, id) {
+  return normalizeStore(store).connections.some((connection) => connection.id === id);
+}
+
+export function upsertConnection(store, connection) {
+  if (!isConnection(connection)) throw new Error("Invalid Circular connection");
+  const normalized = normalizeStore(store);
+  const connections = [
+    connection,
+    ...normalized.connections.filter((entry) => entry.id !== connection.id),
+  ];
+  return { version: 1, currentConnectionId: connection.id, connections };
+}
+
+export function removeConnection(store, id) {
+  const normalized = normalizeStore(store);
+  const connections = normalized.connections.filter((entry) => entry.id !== id);
+  return {
+    version: 1,
+    currentConnectionId: normalized.currentConnectionId === id ? null : normalized.currentConnectionId,
+    connections,
+  };
+}
+
+export function publicConnectionRecord(connection) {
+  if (!connection) return null;
+  const { token: _token, ...safe } = connection;
+  return safe;
+}
+
+function stripTrailingSlash(url) {
+  return typeof url === "string" ? url.replace(/\/+$/, "") : url;
+}
+
+function assertValidStore(store, path) {
+  if (!store || typeof store !== "object" || Array.isArray(store)) {
+    throw new Error(`Invalid Circular connections file at ${path}. Expected a versioned connection store.`);
+  }
+  if (store.version !== 1 || !Array.isArray(store.connections)) {
+    throw new Error(`Invalid Circular connections file at ${path}. Expected version 1 with a connections array.`);
+  }
+  if (!(store.currentConnectionId === null || store.currentConnectionId === undefined || typeof store.currentConnectionId === "string")) {
+    throw new Error(`Invalid Circular connections file at ${path}. currentConnectionId must be a string or null.`);
+  }
+  const invalid = store.connections.find((connection) => !isConnection(connection));
+  if (invalid) {
+    throw new Error(`Invalid Circular connections file at ${path}. Connection entries must include id, name, trusted baseUrl, token, workspaceId and teamId.`);
+  }
+}
+
+function isConnection(value) {
+  return Boolean(
+    value &&
+      typeof value.id === "string" &&
+      typeof value.name === "string" &&
+      typeof value.baseUrl === "string" &&
+      isTrustedCircularOrigin(value.baseUrl) &&
+      typeof value.token === "string" &&
+      typeof value.workspaceId === "string" &&
+      typeof value.teamId === "string",
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/circular-mcp",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Dependency-free stdio MCP server for the Circular Agent API — plan work into Circular as tracked tasks and subtasks.",
   "keywords": [
     "circular",