@bevel-software/platform-core-backend 0.33.0 → 0.34.0

package/src/modules/mcp/mcp.routes.ts

@@ -16,6 +16,8 @@ import type { BevelOAuthProvider } from './oauth/bevel-oauth-provider.js';
 import '../tool-auth/index.js'; // req.externalApiKeyId augmentation
 import './mcp-auth.middleware.js'; // req.mcpCallerKind augmentation
 import { isPagePath } from '../audit/index.js';
+import type { IAgentScopeResolver } from '../agent-scope/index.js';
+import { NOT_AN_AGENT_CHOICE } from './oauth/oauth-consent.routes.js';
 
 /** Pull the raw bearer token off an already-authenticated request. */
 function extractBearer(req: Request): string {
@@ -104,6 +106,11 @@ export function createMcpRoutes(
   // RFC 9728 pointer carried on this router's own 401 challenges (the
   // local-token exchange), same value McpAuthMiddleware advertises.
   resourceMetadataUrl: string,
+  /**
+   * The "Connect as" choices a key may be minted as (`modules/agent-scope`).
+   * Absent: keys are minted as Everything only, and no choices are listed.
+   */
+  agents?: Pick<IAgentScopeResolver, 'listChoices' | 'choosable'>,
 ): express.Router {
   const router = express.Router();
 
@@ -153,6 +160,10 @@ export function createMcpRoutes(
           // exchanged grant; undefined for keys/JWTs) — the Audit log's other
           // principal, resolved per request like the key id.
           connectionId: req.agentConnectionId ?? null,
+          // The agent configuration the credential connects as (a key's, an agent
+          // connection's, or the one an exchanged grant carries); null is
+          // Everything. Resolved per request like the ids above.
+          ...(req.mcpAgentPath ? { agentPath: req.mcpAgentPath } : {}),
           // The proxy authenticates its loopback calls with the SAME bearer the
           // client used here, so it acts on the request exactly as the caller would.
           bearer: extractBearer(req),
@@ -233,6 +244,17 @@ export function createMcpRoutes(
 
   // ── Connection-key management (JWT-only) ───────────────────────────────
 
+  // The agents a key may be minted as — the same choices the OAuth consent
+  // step offers below Everything, for the key-mint dialog.
+  router.get('/mcp/agent-choices', jwtAuthMiddleware, async (req, res) => {
+    try {
+      res.json({ agents: agents && req.userEmail ? await agents.listChoices(req.userEmail) : [] });
+    } catch (err) {
+      log.error('listing the agents to connect as failed:', { err });
+      res.status(500).json({ error: 'Failed to list the agents' });
+    }
+  });
+
   router.get('/mcp/external-api-keys', jwtAuthMiddleware, async (req, res) => {
     try {
       const tokens = await externalApiKeyService.listForUser(req.userId!);
@@ -264,12 +286,23 @@ export function createMcpRoutes(
         res.status(400).json({ error: 'JSON body required' });
         return;
       }
-      const { label } = req.body as { label?: string };
+      const { label, agentPath: asked } = req.body as { label?: string; agentPath?: unknown };
       if (!label) {
         res.status(400).json({ error: 'label is required' });
         return;
       }
-      const minted = await externalApiKeyService.mint(req.userId!, label);
+      // "Connect as", exactly as on the consent step: absent, null or empty is
+      // Everything; anything else must be an agent the owner may choose now.
+      let agentPath: string | null = null;
+      if (asked !== undefined && asked !== null && asked !== '') {
+        agentPath =
+          typeof asked === 'string' && agents && req.userEmail ? await agents.choosable(req.userEmail, asked) : null;
+        if (agentPath === null) {
+          res.status(400).json({ error: NOT_AN_AGENT_CHOICE });
+          return;
+        }
+      }
+      const minted = await externalApiKeyService.mint(req.userId!, label, agentPath ? { agentPath } : {});
       // The plaintext field is the *only* read path for the raw key. The
       // frontend must store it nowhere — it shows the dialog once and then
       // discards. Subsequent fetches return only `summary`-shaped rows.
@@ -428,8 +461,11 @@ export function createMcpRoutes(
       // The grant's agent connection rides along, so the local server's
       // calls with this token stay attributed to the agent in the Audit log.
       const connectionId = typeof info.extra?.connectionId === 'string' ? info.extra.connectionId : undefined;
+      // So does the agent the connection was made as: the local server's
+      // calls see the same narrowed surface as the hosted endpoint's.
+      const agentPath = typeof info.extra?.agentPath === 'string' && info.extra.agentPath ? info.extra.agentPath : undefined;
       const minted = internalTokens.mint(
-        { userId, externalProxy: true, ...(connectionId ? { connectionId } : {}) },
+        { userId, externalProxy: true, ...(connectionId ? { connectionId } : {}), ...(agentPath ? { agentPath } : {}) },
         ttlMs,
       );
       // The ACTUAL lifetime, not the constant — the caller schedules its

package/src/modules/mcp/mcp.service.ts

@@ -75,6 +75,16 @@ import {
   type ComposedAgentInstructions,
 } from '../agent-instructions/index.js';
 import { guideFirstDescription } from '../tool-registry/index.js';
+import {
+  CONNECTION_META_KEY,
+  connectionRefusal,
+  connectionWireOf,
+  describeConnection,
+  type ConnectionScopeWire,
+} from '@bevel-software/platform-mcp-core';
+
+// Still offered from here, as this module's tests and callers learnt it.
+export { CONNECTION_META_KEY };
 
 /**
  * Configuration for the loopback proxy. `loopbackBaseUrl` is the backend's own
@@ -142,6 +152,14 @@ export interface McpCaller {
    * attributed in the Audit log; a request with neither records nothing.
    */
   connectionId?: string | null;
+  /**
+   * The agent configuration the caller's credential connects as (a connection
+   * key's, or an agent connection's), or null for Everything. It rides the
+   * request's loopback identity, so every agent surface behind the loopback
+   * narrows to that agent's scope (`modules/agent-scope`); here it only keys
+   * the surface and words the handshake.
+   */
+  agentPath?: string | null;
   /** The raw bearer the request carried. */
   bearer: string;
   /**
@@ -222,6 +240,24 @@ interface RequestSurface {
    * build, at the latest after an hour unused.
    */
   degraded: boolean;
+  /**
+   * The agent the catalog was narrowed to, as `all-tools` reported it —
+   * absent for Everything. A call to a tool not on a narrowed surface is
+   * refused by name and agent rather than as unknown, and a connection whose
+   * agent configuration cannot be used is served nothing, with the sentence that says
+   * why.
+   */
+  connection?: ConnectionScopeWire;
+}
+
+/**
+ * The `connection` a loopback answer (`all-tools`, `catalog-revision`)
+ * carries, as a field to spread: validated at the boundary by the MCP
+ * core's reader (HTTP loses the type), and absent for Everything.
+ */
+function connectionOf(body: unknown): { connection?: ConnectionScopeWire } {
+  const connection = connectionWireOf(body);
+  return connection ? { connection } : {};
 }
 
 /**
@@ -490,13 +526,26 @@ export class McpService {
     // verifier resolves it to `source: 'external'`: the caller IS an external
     // agent and must be treated like one (admitted to `start_session`/`ask`,
     // refused from internal-only tools).
+    // The agent the connection was made as rides that token too, so the
+    // surfaces behind the loopback narrow to its scope; a connection key
+    // carries its own.
+    const agentPath = caller.agentPath || null;
     const loopbackBearer =
       tokenId == null && this.internalTokens
-        ? this.internalTokens.mint({ userId, externalProxy: true }, MCP_LOOPBACK_TOKEN_TTL_MS)
+        ? this.internalTokens.mint(
+            { userId, externalProxy: true, ...(agentPath ? { agentPath } : {}) },
+            MCP_LOOPBACK_TOKEN_TTL_MS,
+          )
         : bearer;
 
     let instructions: Promise<ComposedAgentInstructions> | undefined;
     const agentInstructions = () => (instructions ??= this.composeAgentInstructions());
+    // What a narrowed connection is told about itself at the handshake: the
+    // agent it is connected as, or why it loads nothing. Read off the catalog
+    // revision (cheap), not the surface (a full discovery). Everything is
+    // told nothing new, so its handshake is exactly what it was.
+    const connectionLine = async (): Promise<string | null> =>
+      agentPath ? describeConnection((await this.fetchCatalogRevision(loopbackBearer)).connection) : null;
     // The Audit log's view of this request — only when the request can be
     // attributed to a key, an agent connection or a page. The catalog names
     // it classifies pooled tools by are the surface's, which is looked up
@@ -534,6 +583,10 @@ export class McpService {
       }));
 
     const initializing = (Array.isArray(messages) ? messages : [messages]).some((m) => isInitializeRequest(m));
+    const handshakeInstructions = async (): Promise<string> => {
+      const [{ instructions: text }, line] = await Promise.all([agentInstructions(), connectionLine()]);
+      return line ? `${text}\n\n${line}` : text;
+    };
     // The deployment's MCP Apps, read once per request. Declaring the
     // `resources` capability is what permits the two handlers below, and a
     // deployment with no view must not declare it — a client would then list
@@ -554,12 +607,12 @@ export class McpService {
         },
         // `instructions` rides the initialize result; clients that honour it
         // place the text in the model's system prompt without the model acting.
-        ...(initializing ? { instructions: (await agentInstructions()).instructions } : {}),
+        ...(initializing ? { instructions: await handshakeInstructions() } : {}),
       },
     );
 
     server.setRequestHandler(ListToolsRequestSchema, async () => inRequest(async () => {
-      const [{ tools, catalogNames }, { toolPrefix }, readOnly] = await Promise.all([
+      const [{ tools, catalogNames, connection }, { toolPrefix }, readOnly] = await Promise.all([
         requestSurface(),
         agentInstructions(),
         // A failed read lists the built-in hints rather than no listing at all.
@@ -568,6 +621,12 @@ export class McpService {
           return undefined;
         }),
       ]);
+      // A connection whose agent configuration cannot be used is served NOTHING — not
+      // Everything — and the one sentence saying why rides the listing's
+      // `_meta` (the handshake carries it too).
+      if (connection?.unavailable) {
+        return { tools: [], _meta: { [CONNECTION_META_KEY]: connection.unavailable } };
+      }
       // A discovered tool whose name collides with a meta-tool would be
       // listed but never callable (the dispatcher routes the name to the
       // meta-tool first), so drop it from the listing entirely.
@@ -694,7 +753,10 @@ export class McpService {
     }
 
     server.setRequestHandler(CallToolRequestSchema, async (request, extra) => inRequest(async () => {
-      const { client: shared, tools, unavailable, catalogNames, hidden: hiddenTools } = await requestSurface();
+      const { client: shared, tools, unavailable, catalogNames, hidden: hiddenTools, connection } = await requestSurface();
+      // Nothing is callable on a connection that loads nothing, meta-tools
+      // included: every call is answered with the reason.
+      if (connection?.unavailable) return toolError(connection.unavailable);
       // The person's client, as this request uses it: every call it makes —
       // a chain's too, which comes back from the isolate outside any async
       // context — carries this request's bearer and audit.
@@ -769,7 +831,16 @@ export class McpService {
         if (answer && owner && audit) {
           await audit.denied(`${owner.utcpName}.${toolName.slice(owner.utcpName.length + 1)}`, args);
         }
-        return answer ?? toolError(retiredToolMessage(toolName) ?? `Unknown tool "${toolName}".`);
+        // On a narrowed connection, a tool off the surface is one its agent
+        // does not load: refused by name and agent, never "unknown" — the tool
+        // may well exist, for this person, on another connection.
+        return (
+          answer ??
+          toolError(
+            retiredToolMessage(toolName) ??
+              (connection ? connectionRefusal(toolName, connection) : `Unknown tool "${toolName}".`),
+          )
+        );
       }
       const needsAuth = await needsAuthorization(proxied.manualName);
       if (needsAuth) {
@@ -879,9 +950,20 @@ export class McpService {
    */
   private async surfaceFor(caller: McpCaller, loopbackBearer: string): Promise<RequestSurface> {
     const { userId, tokenId } = caller;
-    const revision = await this.fetchCatalogRevision(loopbackBearer);
+    const { revision } = await this.fetchCatalogRevision(loopbackBearer);
     if (revision === null) return this.buildSurface(userId, tokenId, loopbackBearer, 'uncached');
-    const key = [userId, tokenId != null ? 'key' : 'person', caller.scope ?? 'write', revision].join(POOL_KEY_SEPARATOR);
+    // The agent the connection was made as is part of the key: two
+    // connections of one person made as different agents are two surfaces.
+    // (The revision already moves when the agent's FILE changes — it carries
+    // the file's digest — so an edit is a new build at the next request.)
+    // Everything adds nothing, and keeps the key it always had.
+    const key = [
+      userId,
+      tokenId != null ? 'key' : 'person',
+      caller.scope ?? 'write',
+      revision,
+      ...(caller.agentPath ? [caller.agentPath] : []),
+    ].join(POOL_KEY_SEPARATOR);
     const { value } = await this.surfaces.get(
       key,
       () => this.buildSurface(userId, tokenId, loopbackBearer, 'miss'),
@@ -893,10 +975,13 @@ export class McpService {
   /**
    * The caller's catalog revision (`GET /api/agent/catalog-revision`, the one
    * `hexis-mcp` polls), read with their bearer; null when it cannot be read.
+   * With it, the agent the caller's connection is narrowed to, when it is.
    * A deployment or a test that does not serve the route answers 404, which
    * is not worth a line in the log; anything else is.
    */
-  private async fetchCatalogRevision(bearer: string): Promise<string | null> {
+  private async fetchCatalogRevision(
+    bearer: string,
+  ): Promise<{ revision: string | null; connection?: ConnectionScopeWire }> {
     try {
       const res = await fetch(`${this.opts.loopbackBaseUrl}/api/agent/catalog-revision`, {
         headers: { Authorization: `Bearer ${bearer}` },
@@ -904,13 +989,16 @@ export class McpService {
       });
       if (!res.ok) {
         if (res.status !== 404) log.warn(`catalog-revision loopback failed: HTTP ${res.status}; building this request's surface uncached`);
-        return null;
+        return { revision: null };
       }
-      const body = (await res.json()) as { revision?: unknown };
-      return typeof body.revision === 'string' && body.revision ? body.revision : null;
+      const body = (await res.json()) as { revision?: unknown; connection?: unknown };
+      return {
+        revision: typeof body.revision === 'string' && body.revision ? body.revision : null,
+        ...connectionOf(body),
+      };
     } catch (err) {
       log.warn("catalog-revision loopback threw; building this request's surface uncached:", { err });
-      return null;
+      return { revision: null };
     }
   }
 
@@ -935,7 +1023,7 @@ export class McpService {
     // The list of manuals this caller gets: the KB manual + each `.tool` they
     // can read. Fetched over loopback with the caller's key, so ACL filtering
     // lives ONCE behind the REST surface.
-    const manuals = await this.fetchManualTemplates(loopbackBearer);
+    const { manuals, connection } = await this.fetchManualTemplates(loopbackBearer);
     const catalogMs = performance.now() - started;
     const client = await this.buildClient(userId, manuals);
     const discovered = await this.discoverTools(client, manuals, userId);
@@ -960,7 +1048,7 @@ export class McpService {
           (decision.suppressed > 0 ? ` [+${decision.suppressed} identical rebuild(s) since last line]` : ''),
       );
     }
-    return { ...discovered, client, tools };
+    return { ...discovered, client, tools, ...(connection ? { connection } : {}) };
   }
 
   /**
@@ -1039,11 +1127,13 @@ export class McpService {
    * request. HTTP transport loses the `CallTemplate` type, so we re-validate the
    * received JSON even though the producing endpoint already validated it.
    */
-  private async fetchManualTemplates(bearer: string): Promise<CallTemplate[]> {
+  private async fetchManualTemplates(
+    bearer: string,
+  ): Promise<{ manuals: CallTemplate[]; connection?: ConnectionScopeWire }> {
     // This is the REMOTE proxy, so ask for remote-capable manuals only — local-only
     // `.tool`s are surfaced instead via the `list_local_tools` tool in the KB manual.
     const body = (await this.loopbackJson(bearer, '/api/agent/all-tools?remote=true', 'all-tools')) as
-      | { manuals?: unknown }
+      | { manuals?: unknown; connection?: unknown }
       | null;
     const rawManuals: unknown[] = Array.isArray(body?.manuals) ? body.manuals : [];
 
@@ -1062,7 +1152,7 @@ export class McpService {
     }
     // Always include the KB manual, even if `all-tools` was unavailable/regressed.
     if (!hasKb) out.unshift(this.kbManualTemplate());
-    return out;
+    return { manuals: out, ...connectionOf(body) };
   }
 
   /** The KB manual's discovery template — the fallback if `all-tools` is unavailable. */

package/src/modules/mcp/oauth/bevel-oauth-provider.ts

@@ -199,10 +199,16 @@ export class BevelOAuthProvider implements OAuthServerProvider {
    * Called by the Finish endpoint once an authenticated user completes the
    * /connect step: bind a one-time code to (user, client, redirect_uri, PKCE
    * challenge) and hand back the client redirect the browser should follow.
+   *
+   * @param agentPath The "Connect as" choice — an agent configuration the consent
+   *   route has already checked the person may choose — or null for
+   *   Everything. Carried on the code to the exchange, which records it on
+   *   the agent connection.
    */
   async issueAuthCode(
     userId: string,
     st: McpAuthRequestState,
+    agentPath: string | null = null,
   ): Promise<{ redirectTo: string }> {
     // A state without a PKCE challenge is a Claude-link request, which the
     // marketplace bridge finishes; it must never reach the SDK's code store.
@@ -217,6 +223,7 @@ export class BevelOAuthProvider implements OAuthServerProvider {
       scope: st.sc ?? null,
       resource: st.rs ?? null,
       expiresAt: new Date(Date.now() + CODE_TTL_MS),
+      ...(agentPath ? { agentPath } : {}),
     });
     const redirect = new URL(st.r);
     redirect.searchParams.set('code', code);
@@ -269,7 +276,7 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     if (redirectUri && redirectUri !== row.redirectUri) {
       throw new InvalidGrantError('redirect_uri does not match the authorization request');
     }
-    return this.mintTokens(row.userId, row.clientId, row.scope, row.resource);
+    return this.mintTokens(row.userId, row.clientId, row.scope, row.resource, undefined, undefined, row.agentPath ?? null);
   }
 
   async exchangeRefreshToken(
@@ -463,6 +470,7 @@ export class BevelOAuthProvider implements OAuthServerProvider {
         id: oauthTokens.id,
         clientId: oauthTokens.clientId,
         connectionId: oauthTokens.connectionId,
+        agentPath: agentConnections.agentPath,
         scope: oauthTokens.scope,
         resource: oauthTokens.resource,
         expiresAt: oauthTokens.expiresAt,
@@ -507,6 +515,10 @@ export class BevelOAuthProvider implements OAuthServerProvider {
         // Null on a token minted before connections existed; the auth
         // middleware then binds no agent and the call goes unrecorded.
         connectionId: row.connectionId,
+        // The connection's "Connect as" choice, read off the row on every
+        // verification, so a re-consent with another choice reaches the
+        // agent's very next request. Null is Everything.
+        agentPath: row.agentPath ?? null,
       },
     };
   }
@@ -575,6 +587,9 @@ export class BevelOAuthProvider implements OAuthServerProvider {
    *   first mint, which finds or makes the live connection for (user, client).
    * @param tx The transaction the insert belongs to, when the mint must land
    *   with the statement that consumed the token it replaces (a refresh).
+   * @param agentPath The consent's "Connect as" choice, recorded on the
+   *   connection the pair is bound to (null: Everything). Only a first mint —
+   *   a consent — passes it; a refresh leaves the connection's choice alone.
    *   The prune is then the caller's, before the transaction opens: a
    *   best-effort statement that fails inside a transaction would abort the
    *   mint it is meant to spare, and one on the pool from inside it would
@@ -587,6 +602,7 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     resource: string | null,
     connectionId?: string,
     tx?: Tx,
+    agentPath?: string | null,
   ): Promise<OAuthTokens> {
     const accessToken = this.deps.tokenPrefix + randomBytes(TOKEN_BYTES).toString('base64url');
     const refreshToken = this.refreshPrefix + randomBytes(TOKEN_BYTES).toString('base64url');
@@ -594,7 +610,7 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     // A mint of its own (a sign-in) prunes here; a refresh pruned before its
     // transaction opened.
     if (!tx) await this.pruneTokenTables(now);
-    const boundTo = connectionId ?? (await this.ensureConnection(userId, clientId));
+    const boundTo = connectionId ?? (await this.ensureConnection(userId, clientId, agentPath));
     const sink: Tx | Database = tx ?? this.deps.db;
     await sink.insert(oauthTokens).values({
       accessTokenHash: hashToken(accessToken),
@@ -665,12 +681,23 @@ export class BevelOAuthProvider implements OAuthServerProvider {
    * revoke. A read, not a write: the use is stamped separately, throttled.
    */
   async isConnectionLive(connectionId: string): Promise<boolean> {
+    return (await this.liveConnectionChoice(connectionId)) !== null;
+  }
+
+  /**
+   * A live agent connection's current "Connect as" choice (`agentPath` null
+   * = Everything), or null when the connection is gone or revoked. Read on
+   * every request through the local server's exchanged grant: that token is
+   * stateless and outlives a re-consent, so the choice it was minted with is
+   * not the one it is served as — the row's is.
+   */
+  async liveConnectionChoice(connectionId: string): Promise<{ agentPath: string | null } | null> {
     const [row] = await this.deps.db
-      .select({ id: agentConnections.id })
+      .select({ agentPath: agentConnections.agentPath })
       .from(agentConnections)
       .where(and(eq(agentConnections.id, connectionId), isNull(agentConnections.revokedAt)))
       .limit(1);
-    return row !== undefined;
+    return row ? { agentPath: row.agentPath ?? null } : null;
   }
 
   /**
@@ -737,8 +764,13 @@ export class BevelOAuthProvider implements OAuthServerProvider {
    * the other's `ON CONFLICT DO NOTHING` returns no row, and it re-reads the
    * winner's. The client's display name is snapshotted from its registration
    * at that moment.
+   *
+   * `agentPath` is a consent's "Connect as" choice: written on the row made,
+   * and on the live row found — the person's latest consent is what the agent
+   * connects as. `undefined` (a refresh of a token from before connections
+   * existed) leaves a found row's choice as it is.
    */
-  private async ensureConnection(userId: string, clientId: string): Promise<string> {
+  private async ensureConnection(userId: string, clientId: string, agentPath?: string | null): Promise<string> {
     const [client] = await this.deps.db
       .select({ clientName: oauthClients.clientName })
       .from(oauthClients)
@@ -758,11 +790,17 @@ export class BevelOAuthProvider implements OAuthServerProvider {
           ),
         )
         .limit(1);
+    const choose = async (id: string): Promise<string> => {
+      if (agentPath !== undefined) {
+        await this.deps.db.update(agentConnections).set({ agentPath }).where(eq(agentConnections.id, id));
+      }
+      return id;
+    };
     const [existing] = await live();
-    if (existing) return existing.id;
+    if (existing) return choose(existing.id);
     const [inserted] = await this.deps.db
       .insert(agentConnections)
-      .values({ userId, clientId, clientName, agentKey })
+      .values({ userId, clientId, clientName, agentKey, ...(agentPath ? { agentPath } : {}) })
       .onConflictDoNothing({
         target: [agentConnections.userId, agentConnections.agentKey],
         where: sql`${agentConnections.revokedAt} is null`,
@@ -771,7 +809,7 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     if (inserted) return inserted.id;
     const [winner] = await live();
     if (!winner) throw new Error('agent connection vanished between insert and re-read');
-    return winner.id;
+    return choose(winner.id);
   }
 }
 

package/src/modules/mcp/oauth/oauth-consent.routes.ts

@@ -4,6 +4,7 @@ import { logger } from '../../../shared/logging.js';
 const log = logger('mcp-oauth');
 import type { BevelOAuthProvider } from './bevel-oauth-provider.js';
 import { verifyAuthRequest, type McpAuthRequestState } from './oauth-state.js';
+import type { IAgentScopeResolver } from '../../agent-scope/index.js';
 import '../../auth/index.js'; // Express Request augmentation (req.userId / req.userEmail)
 
 export interface OAuthConsentRoutesDeps {
@@ -21,8 +22,17 @@ export interface OAuthConsentRoutesDeps {
     clientNameFor(st: McpAuthRequestState): string;
     completeConsent(userId: string, st: McpAuthRequestState): Promise<{ redirectTo: string }>;
   };
+  /**
+   * The "Connect as" choices: the agent configurations the person may connect an
+   * MCP client as, offered below Everything. Absent, the consent offers
+   * Everything alone and Finish refuses any other choice.
+   */
+  agents?: Pick<IAgentScopeResolver, 'listChoices' | 'choosable'>;
 }
 
+/** The refusal of a choice that is not one of the person's — one answer for missing and unreadable. */
+export const NOT_AN_AGENT_CHOICE = 'That agent is not one you can connect as. Choose Everything or one of the agents listed.';
+
 /**
  * The authenticated tail of the MCP OAuth flow. `/authorize` (SDK-owned)
  * validated the client's request, packed it into a signed state, and sent the
@@ -49,10 +59,25 @@ export function createOAuthConsentRoutes(deps: OAuthConsentRoutesDeps): express.
       return;
     }
     const client = await deps.provider.clientsStore.getClient(st.c);
+    // Everything is not in the list: it is the choice every consent has, and
+    // the one the page selects. A failure to read the agents costs the choice
+    // of an agent, never the consent itself — but it is SAID
+    // (`agentsUnavailable`), so the page does not pass an empty list off as
+    // "you have no agents" and approve Everything unasked.
+    let agentsUnavailable = false;
+    const agents = deps.agents && req.userEmail
+      ? await deps.agents.listChoices(req.userEmail).catch((err: unknown) => {
+          log.warn('listing the agents to connect as failed:', { detail: err instanceof Error ? err.message : String(err) });
+          agentsUnavailable = true;
+          return [];
+        })
+      : [];
     res.json({
       clientName: client?.client_name ?? null,
       scope: st.sc ?? null,
       resource: st.rs ?? null,
+      agents,
+      ...(agentsUnavailable ? { agentsUnavailable: true } : {}),
     });
   });
 
@@ -65,10 +90,25 @@ export function createOAuthConsentRoutes(deps: OAuthConsentRoutesDeps): express.
     const st = raw ? verifyAuthRequest(deps.stateSecret, raw) : null;
     if (!st) return void res.status(400).json({ error: 'Invalid or expired authorization request. Restart the connection from your agent.' });
     if (st.gh && !deps.facade) return void res.status(400).json({ error: NO_FACADE });
+    // "Connect as": absent, null or empty is Everything. Anything else must be
+    // an agent the person may choose right now — checked here, at the only
+    // place a choice is made, so the token exchange records it as given.
+    const asked: unknown = (req.body ?? {}).agentPath;
+    if (asked !== undefined && asked !== null && typeof asked !== 'string') {
+      return void res.status(400).json({ error: NOT_AN_AGENT_CHOICE });
+    }
+    const choosing = typeof asked === 'string' && asked.trim() !== '';
+    // An account linked through the GitHub facade has no agent connection to
+    // record a choice on.
+    if (choosing && (st.gh || !deps.agents || !req.userEmail)) {
+      return void res.status(400).json({ error: NOT_AN_AGENT_CHOICE });
+    }
     try {
+      const agentPath = choosing && deps.agents && req.userEmail ? await deps.agents.choosable(req.userEmail, asked as string) : null;
+      if (choosing && agentPath === null) return void res.status(400).json({ error: NOT_AN_AGENT_CHOICE });
       const { redirectTo } = st.gh && deps.facade
         ? await deps.facade.completeConsent(userId, st)
-        : await deps.provider.issueAuthCode(userId, st);
+        : await deps.provider.issueAuthCode(userId, st, agentPath);
       res.json({ redirectTo });
     } catch (err) {
       // Message only — the raw error object can carry sensitive context

package/src/modules/plugins/__tests__/plugins.tools.test.ts

@@ -13,6 +13,8 @@ import { GUIDE_FIRST_SENTENCE } from '../../tool-registry/guide-first.js';
 import { registerPluginsTools, CREATE_PLUGIN, myPluginDef, myPluginDescription } from '../plugins.tools.js';
 import { createPluginCreationRoutes } from '../plugins.routes.js';
 import { PluginProvisionError } from '../plugin-provision.service.js';
+import type { IAgentScopeResolver } from '../../agent-scope/index.js';
+import { agentFile, agentScopeOver, inMemoryKb } from '../../agent-scope/__tests__/in-memory-kb.js';
 
 /**
  * The plugin tools are DESCRIPTIONS of the app's own creation endpoints.
@@ -200,7 +202,12 @@ describe('the creation endpoints behind the key-or-session gate', () => {
 
   const externalApiKeyService = {
     looksLikeExternalApiKey: (t: string) => typeof t === 'string' && t.startsWith('bevel_'),
-    verifyAndLoadToken: async (t: string) => (t === 'bevel_alice' ? { user: ALICE, tokenId: 'tok-a' } : null),
+    verifyAndLoadToken: async (t: string) =>
+      t === 'bevel_alice'
+        ? { user: ALICE, tokenId: 'tok-a' }
+        : t === 'bevel_alice_agent'
+          ? { user: ALICE, tokenId: 'tok-b', agentPath: 'Agents/plugin-maker.agent' }
+          : null,
   } as never;
   const authService = {
     getUserById: async (id: string) => (id === ALICE.id ? ALICE : null),
@@ -211,7 +218,7 @@ describe('the creation endpoints behind the key-or-session gate', () => {
     },
   } as never;
 
-  async function start(): Promise<string> {
+  async function start(agentScope?: Pick<IAgentScopeResolver, 'resolve'>): Promise<string> {
     const internalToken = new InternalTokenService({ secret: 'test-secret' });
     const app = express();
     app.use(express.json());
@@ -224,6 +231,7 @@ describe('the creation endpoints behind the key-or-session gate', () => {
       }),
       createPluginCreationRoutes({ ensurePersonalPlugin, createPlugin } as never, async (req) =>
         req.userId ? ((await (authService as { getUserById(id: string): Promise<unknown> }).getUserById(req.userId)) as never) : null,
+        agentScope,
       ),
     );
     httpServer = await new Promise<HttpServer>((r) => {
@@ -302,4 +310,32 @@ describe('the creation endpoints behind the key-or-session gate', () => {
     );
     expect(createPlugin).not.toHaveBeenCalled();
   });
+
+  it("refuses a connection made as an .agent that does not list the tool, by name, before anything is provisioned", async () => {
+    // The agent lists `my_plugin` only. These routes are not hosted by
+    // `toolHandler`, so they make its connection-scope check themselves.
+    const kb = inMemoryKb(
+      { 'Agents/plugin-maker.agent': agentFile('name: Plugin maker\nplatformTools: [my_plugin]') },
+      { reader: ALICE.email },
+    );
+    const base = await start(agentScopeOver(kb));
+    const refused = await post(base, '/api/plugins', { name: 'GTM' }, 'bevel_alice_agent');
+    expect(refused.status).toBe(403);
+    expect(await refused.json()).toEqual({
+      error: expect.stringContaining('The tool "create_plugin" is not available to this connection'),
+      code: 'not_available_to_connection',
+    });
+    expect(createPlugin).not.toHaveBeenCalled();
+
+    // The tool it lists is served; a key made as Everything and a session are untouched.
+    expect((await post(base, '/api/plugins/personal', {}, 'bevel_alice_agent')).status).toBe(200);
+    expect((await post(base, '/api/plugins', { name: 'Ops' }, 'bevel_alice')).status).toBe(201);
+    expect((await post(base, '/api/plugins', { name: 'Fin' }, 'session-alice')).status).toBe(201);
+  });
+
+  it('a narrowed connection with no scope resolver wired loads nothing, never Everything', async () => {
+    const base = await start();
+    expect((await post(base, '/api/plugins/personal', {}, 'bevel_alice_agent')).status).toBe(403);
+    expect(ensurePersonalPlugin).not.toHaveBeenCalled();
+  });
 });

package/src/modules/plugins/index.ts

@@ -19,7 +19,7 @@ export {
   type JoinRequestStatus,
   type JoinRequestStore,
 } from './join-request-records.store.js';
-export { PluginLinkIndex, type LinkMembership, type PluginLinks } from './plugin-links.js';
+export { PluginLinkIndex, type IPluginLinkIndex, type LinkMembership, type PluginLinks } from './plugin-links.js';
 export { PluginLinksService, PluginLinkError } from './plugin-links.service.js';
 export { PluginRenameService, PluginRenameError, renamePluginPrincipalInText } from './plugin-rename.service.js';
 export { compileMarketplace, type VirtualTree, type CompileInput, type MarketplaceOptions } from './compile/compile-marketplace.js';