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

package/src/modules/mcp/__tests__/connect-as.pg.test.ts

@@ -0,0 +1,137 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { randomBytes } from 'node:crypto';
+import { eq } from 'drizzle-orm';
+import { migrate } from 'drizzle-orm/node-postgres/migrator';
+import type { OAuthClientInformationFull } from '@modelcontextprotocol/sdk/shared/auth.js';
+import { BevelOAuthProvider } from '../oauth/bevel-oauth-provider.js';
+import { ExternalApiKeyService } from '../../tool-auth/external-api-key.service.js';
+import { closeDb, createDb, type Database } from '../../database/connection.js';
+import { agentConnections, externalApiKeys, oauthClients, users } from '../../database/core-schema.js';
+import { coreMigrationsDir } from '../../../assets.js';
+import { PG_ADMIN_URL, PG_TEST_TIMEOUT, dropScratchDatabases, scratchDatabaseUrl } from '../../../__tests__/pg-scratch.js';
+
+/**
+ * The "Connect as" choice, through the real intermediary it is stored in: a
+ * migrated Postgres. The consent's choice goes onto the one-time code at
+ * Finish, crosses the token exchange onto the agent connection, and comes back
+ * out of every access-token verification; a key's choice goes onto its row at
+ * mint and comes back out of every key verification. Driven through the
+ * provider's and the key service's public surfaces only. Skipped without
+ * `TEST_DATABASE_URL`, as every `*.pg.test.ts` is.
+ */
+
+const PREFIX = 'bevel-mcp_';
+const REDIRECT = 'https://agent.example.com/callback';
+
+describe.skipIf(!PG_ADMIN_URL)('connecting as an agent, on a real Postgres', () => {
+  let db: Database;
+  let provider: BevelOAuthProvider;
+
+  beforeAll(async () => {
+    db = createDb(await scratchDatabaseUrl('hexis_connect_as'), { piiKey: randomBytes(32).toString('base64') });
+    await migrate(db, { migrationsFolder: coreMigrationsDir() });
+    provider = new BevelOAuthProvider({
+      db,
+      crypto: null,
+      stateSecret: 'test-state-secret',
+      publicFrontendUrl: 'https://app.example.com',
+      tokenPrefix: PREFIX,
+    });
+    vi.spyOn(console, 'log').mockImplementation(() => undefined);
+  }, PG_TEST_TIMEOUT);
+
+  afterAll(async () => {
+    vi.restoreAllMocks();
+    await closeDb(db);
+    await dropScratchDatabases();
+  }, PG_TEST_TIMEOUT);
+
+  async function person(tag: string): Promise<string> {
+    const [user] = await db
+      .insert(users)
+      .values({ email: `${tag}@example.com`, emailBidx: `${tag}@example.com`, name: tag })
+      .returning({ id: users.id });
+    return user!.id;
+  }
+
+  async function registeredClient(tag: string): Promise<OAuthClientInformationFull> {
+    const clientId = `client-${tag}-${randomBytes(4).toString('hex')}`;
+    await db.insert(oauthClients).values({ clientId, clientName: 'Claude', redirectUris: [REDIRECT] });
+    return { client_id: clientId, redirect_uris: [REDIRECT], token_endpoint_auth_method: 'none' };
+  }
+
+  /** Finish on the consent step with `agentPath` (undefined: the route's Everything), then the client's exchange. */
+  async function consent(userId: string, client: OAuthClientInformationFull, agentPath?: string | null) {
+    const st = { c: client.client_id, r: REDIRECT, cc: 'challenge', iat: Date.now() };
+    const { redirectTo } =
+      agentPath === undefined ? await provider.issueAuthCode(userId, st) : await provider.issueAuthCode(userId, st, agentPath);
+    const code = new URL(redirectTo).searchParams.get('code')!;
+    return provider.exchangeAuthorizationCode(client, code);
+  }
+
+  const connectionsOf = (userId: string) =>
+    db
+      .select({ id: agentConnections.id, agentPath: agentConnections.agentPath, revokedAt: agentConnections.revokedAt })
+      .from(agentConnections)
+      .where(eq(agentConnections.userId, userId));
+
+  it('Everything: a consent with no choice records null and verifies with none — exactly as before', async () => {
+    const userId = await person('everything');
+    const tokens = await consent(userId, await registeredClient('everything'));
+    expect(await connectionsOf(userId)).toEqual([{ id: expect.any(String), agentPath: null, revokedAt: null }]);
+    expect((await provider.verifyAccessToken(tokens.access_token)).extra?.agentPath).toBeNull();
+  });
+
+  it("the consent's choice round-trips to the connection row, and out of every verification", async () => {
+    const userId = await person('ada');
+    const client = await registeredClient('ada');
+    const tokens = await consent(userId, client, 'Agents/delivery-mechanic.agent');
+
+    const [row] = await connectionsOf(userId);
+    expect(row!.agentPath).toBe('Agents/delivery-mechanic.agent');
+    const info = await provider.verifyAccessToken(tokens.access_token);
+    expect(info.extra).toMatchObject({ connectionId: row!.id, agentPath: 'Agents/delivery-mechanic.agent' });
+
+    // A refresh keeps the connection's choice.
+    const refreshed = await provider.exchangeRefreshToken(client, tokens.refresh_token!);
+    expect((await provider.verifyAccessToken(refreshed.access_token)).extra?.agentPath).toBe('Agents/delivery-mechanic.agent');
+  });
+
+  it('re-consenting with another choice changes the live connection, and its tokens follow it', async () => {
+    const userId = await person('bea');
+    const first = await consent(userId, await registeredClient('bea'), 'Agents/a.agent');
+    // Claude registers afresh on every re-authorisation; the agent is one connection.
+    await consent(userId, await registeredClient('bea'), null);
+
+    const rows = await connectionsOf(userId);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]!.agentPath).toBeNull();
+    // The earlier pair still verifies — and now as the connection's choice.
+    expect((await provider.verifyAccessToken(first.access_token)).extra?.agentPath).toBeNull();
+
+    await consent(userId, await registeredClient('bea'), 'Agents/b.agent');
+    expect((await connectionsOf(userId))[0]!.agentPath).toBe('Agents/b.agent');
+  });
+
+  it("a key's choice is stored at mint and comes back out of every verification", async () => {
+    const userId = await person('cy');
+    const keys = new ExternalApiKeyService(db, 'bevel_');
+    const asAgent = await keys.mint(userId, 'pipeline', { agentPath: 'Agents/ops.agent' });
+    const asEverything = await keys.mint(userId, 'laptop');
+
+    expect(asAgent.summary.agentPath).toBe('Agents/ops.agent');
+    expect(asEverything.summary.agentPath).toBeNull();
+    expect((await keys.verifyAndLoadToken(asAgent.plaintext))?.agentPath).toBe('Agents/ops.agent');
+    expect((await keys.verifyAndLoadToken(asEverything.plaintext))?.agentPath).toBeNull();
+
+    const stored = await db
+      .select({ label: externalApiKeys.label, agentPath: externalApiKeys.agentPath })
+      .from(externalApiKeys)
+      .where(eq(externalApiKeys.userId, userId));
+    expect(stored.sort((a, b) => a.label.localeCompare(b.label))).toEqual([
+      { label: 'laptop', agentPath: null },
+      { label: 'pipeline', agentPath: 'Agents/ops.agent' },
+    ]);
+    expect((await keys.listForUser(userId)).map((k) => k.agentPath).sort()).toEqual(['Agents/ops.agent', null]);
+  });
+});

package/src/modules/mcp/__tests__/mcp-auth.middleware.test.ts

@@ -53,8 +53,8 @@ function makeExternalApiKeyService(
 
 function makeOAuthProvider(
   verify?: (t: string) => Promise<{ extra?: Record<string, unknown> }>,
-  /** Whether an agent connection still admits requests — true unless a test says otherwise. */
-  live?: (connectionId: string) => Promise<boolean>,
+  /** A live agent connection's current choice, or null when revoked — live as Everything unless a test says otherwise. */
+  live?: (connectionId: string) => Promise<{ agentPath: string | null } | null>,
 ) {
   return {
     looksLikeAccessToken: (t: string) => typeof t === 'string' && t.startsWith('bevel-mcp_'),
@@ -64,7 +64,7 @@ function makeOAuthProvider(
           throw new InvalidTokenError('unknown token');
         }),
     ),
-    isConnectionLive: vi.fn(live ?? (async () => true)),
+    liveConnectionChoice: vi.fn(live ?? (async () => ({ agentPath: null }))),
     noteConnectionUse: vi.fn(),
   } as unknown as BevelOAuthProvider;
 }
@@ -318,10 +318,34 @@ describe('createMcpAuthMiddleware', () => {
       expect(req.agentConnectionId).toBe('conn-7');
       // Every request through the exchanged grant asks whether the
       // connection still admits one, and counts as a use of it.
-      expect((oauth as any).isConnectionLive).toHaveBeenCalledWith('conn-7');
+      expect((oauth as any).liveConnectionChoice).toHaveBeenCalledWith('conn-7');
       expect((oauth as any).noteConnectionUse).toHaveBeenCalledWith('conn-7');
     });
 
+    it("serves an exchanged grant as its connection's CURRENT choice, not the one it was minted with", async () => {
+      const auth = makeAuthService();
+      (auth.getUserById as ReturnType<typeof vi.fn>) = vi.fn(async () => ({
+        id: 'user-7',
+        email: 'seven@example.com',
+      }));
+      // Minted as Everything; the person has since re-consented as an agent.
+      const everything = internal.mint({ userId: 'user-7', externalProxy: true, connectionId: 'conn-7' }, 60_000);
+      const narrowed = makeOAuthProvider(undefined, async () => ({ agentPath: 'Agents/narrow.agent' }));
+      const first = makeReqRes(`Bearer ${everything}`);
+      await makeMw({ internal, auth, oauth: narrowed })(first.req, first.res, first.next);
+      expect(first.next).toHaveBeenCalled();
+      expect(first.req.mcpAgentPath).toBe('Agents/narrow.agent');
+      // Minted as an agent; the person has since re-consented as Everything.
+      const asAgent = internal.mint(
+        { userId: 'user-7', externalProxy: true, connectionId: 'conn-7', agentPath: 'Agents/narrow.agent' },
+        60_000,
+      );
+      const second = makeReqRes(`Bearer ${asAgent}`);
+      await makeMw({ internal, auth, oauth: makeOAuthProvider() })(second.req, second.res, second.next);
+      expect(second.next).toHaveBeenCalled();
+      expect(second.req.mcpAgentPath).toBeUndefined();
+    });
+
     it('401s an exchanged grant whose agent connection was revoked — the token is stateless, the connection is not', async () => {
       const token = internal.mint({ userId: 'user-7', externalProxy: true, connectionId: 'conn-7' }, 60_000);
       const auth = makeAuthService();
@@ -329,7 +353,7 @@ describe('createMcpAuthMiddleware', () => {
         id: 'user-7',
         email: 'seven@example.com',
       }));
-      const oauth = makeOAuthProvider(undefined, async () => false);
+      const oauth = makeOAuthProvider(undefined, async () => null);
       const mw = makeMw({ internal, auth, oauth });
       const { req, res, next, status, setHeader } = makeReqRes(`Bearer ${token}`);
       await mw(req, res, next);

package/src/modules/mcp/__tests__/mcp-routes-harness.ts

@@ -29,6 +29,12 @@ import type { McpCallerKind } from '../mcp-auth.middleware.js';
  */
 export const fakeAuth: RequestHandler = (req, _res, next) => {
   req.userId = (req.headers['x-test-user'] as string | undefined) ?? 'user-A';
+  // The signed-in person's email, for a suite whose route reads it.
+  const email = req.headers['x-test-email'] as string | undefined;
+  if (email) req.userEmail = email;
+  // The agent the credential connects as, as the real middleware sets it.
+  const agentPath = req.headers['x-test-agent-path'] as string | undefined;
+  if (agentPath) req.mcpAgentPath = agentPath;
   // The credential kind the real middleware would have recognised, when a
   // suite needs one (the page header is a session's alone).
   const kind = req.headers['x-test-kind'] as McpCallerKind | undefined;
@@ -48,6 +54,7 @@ export interface McpRoutesDeps {
   internalTokens?: unknown;
   oauthProvider?: unknown;
   resourceMetadataUrl?: string;
+  agents?: unknown;
 }
 
 /** Servers opened by `mountMcpRoutes`, closed together by `closeMountedRoutes`. */
@@ -73,6 +80,7 @@ export async function mountMcpRoutes(deps: McpRoutesDeps = {}): Promise<string>
       (deps.internalTokens ?? stub) as never,
       (deps.oauthProvider ?? stub) as never,
       deps.resourceMetadataUrl ?? '',
+      deps.agents as never,
     ),
   );
   const server = await new Promise<HttpServer>((resolve) => {

package/src/modules/mcp/__tests__/mcp.connect-as.test.ts

@@ -0,0 +1,195 @@
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { CONNECTION_META_KEY, McpService, type McpCaller } from '../mcp.service.js';
+import { SpillStore } from '../../workspace/index.js';
+import { createManualRoutes } from '../../tool-registry/manual.routes.js';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { toolDef } from '../../tool-helpers/index.js';
+import type { ConnectionScopeWire } from '../../agent-scope/index.js';
+
+/**
+ * The MCP proxy's half of connecting as an agent. The surfaces behind the
+ * loopback do the narrowing (pinned in the agent-scope suites); what the proxy
+ * owns is the WORDING and the CACHE: a tool off a narrowed surface is refused
+ * by name and agent rather than as unknown, a connection whose file is gone is
+ * served an empty listing with the reason, the handshake says what the
+ * connection is connected as, and two connections of one person made as
+ * different agents never share a built surface.
+ *
+ * The loopback here answers each bearer as the agent surfaces would answer
+ * that credential: `bevel_all` is Everything, `bevel_narrow` an agent that
+ * loads `read_file` alone, `bevel_gone` one whose file was deleted.
+ */
+
+const NARROW: ConnectionScopeWire = { agent: { path: 'Agents/narrow.agent', name: 'narrow' } };
+const GONE: ConnectionScopeWire = {
+  agent: { path: 'Agents/gone.agent', name: 'Agents/gone.agent' },
+  unavailable: 'This connection was made as the agent file `Agents/gone.agent`, which no longer exists.',
+};
+const CONNECTIONS: Record<string, ConnectionScopeWire | undefined> = {
+  bevel_all: undefined,
+  bevel_narrow: NARROW,
+  bevel_gone: GONE,
+};
+
+let httpServer: HttpServer | undefined;
+const cleanups: Array<() => Promise<void>> = [];
+afterEach(async () => {
+  for (const c of cleanups.splice(0)) await c().catch(() => {});
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+  vi.restoreAllMocks();
+});
+
+async function harness() {
+  const state = { builds: 0, base: '' };
+  const connectionOf = (req: express.Request) => CONNECTIONS[(req.headers.authorization ?? '').replace(/^Bearer /, '')];
+  const registry = new ToolRegistry();
+  for (const name of ['read_file', 'edit_file']) {
+    registry.registerExternalTool(
+      toolDef({ name, description: name, path: `/api/agent/tools/${name}`, inputs: { type: 'object', properties: {} } }),
+    );
+  }
+  const app = express();
+  app.use(express.json());
+  app.get('/api/agent/catalog-revision', (req, res) => {
+    const connection = connectionOf(req);
+    res.json({ revision: 'rev-1', tools: 0, skills: 0, ...(connection ? { connection } : {}) });
+  });
+  app.get('/api/agent/all-tools', (req, res) => {
+    state.builds += 1;
+    const connection = connectionOf(req);
+    res.json({ manuals: [], ...(connection ? { connection } : {}) });
+  });
+  // The platform manual, as the agent surfaces narrow it per credential.
+  app.get('/api/agent/utcp', (req, res, next) => {
+    const connection = connectionOf(req);
+    if (!connection) return next();
+    res.json({
+      utcp_version: '1.1.0',
+      manual_version: '1.0.0',
+      tools: connection.unavailable
+        ? []
+        : [
+            {
+              name: 'read_file',
+              description: 'read_file',
+              inputs: { type: 'object', properties: {} },
+              outputs: { type: 'object', properties: {} },
+              tags: [],
+              tool_call_template: {
+                call_template_type: 'http',
+                http_method: 'POST',
+                url: `${state.base}/api/agent/tools/read_file`,
+                content_type: 'application/json',
+              },
+            },
+          ],
+    });
+  });
+  app.use('/api', createManualRoutes(registry, (_req, _res, next) => next()));
+  httpServer = await new Promise<HttpServer>((r) => {
+    const s = app.listen(0, () => r(s));
+  });
+  state.base = `http://127.0.0.1:${(httpServer.address() as { port: number }).port}`;
+  const mcp = new McpService({
+    loopbackBaseUrl: state.base,
+    manualName: 'KNOWLEDGE_BASE',
+    spillStore: new SpillStore(join(tmpdir(), 'bevel-test-spills')),
+    publicFrontendUrl: 'http://localhost:5173',
+  });
+  return { state, mcp };
+}
+
+async function connect(mcp: McpService, caller: Partial<McpCaller>, initialize = false): Promise<Client> {
+  const message = initialize
+    ? { jsonrpc: '2.0', id: 0, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 't', version: '0' } } }
+    : { jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} };
+  const server = await mcp.createRequestServer(
+    { userId: 'user-A', tokenId: 'key-1', connectionId: null, bearer: 'bevel_all', ...caller },
+    message,
+  );
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  await server.connect(serverTransport);
+  const client = new Client({ name: 'test-client', version: '0.0.0' }, { capabilities: {} });
+  await client.connect(clientTransport);
+  cleanups.push(async () => {
+    await client.close();
+    await server.close();
+  });
+  return client;
+}
+
+const textOf = (res: Awaited<ReturnType<Client['callTool']>>) =>
+  (res.content as { type: string; text?: string }[]).find((c) => c.type === 'text')?.text;
+
+describe('a narrowed connection', () => {
+  it('lists what its agent loads, and refuses another tool by name and agent — not as unknown', async () => {
+    const { mcp } = await harness();
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    const client = await connect(mcp, { bearer: 'bevel_narrow', agentPath: 'Agents/narrow.agent' });
+    const names = (await client.listTools()).tools.map((t) => t.name);
+    expect(names).toContain('read_file');
+    expect(names).not.toContain('edit_file');
+    const refused = await client.callTool({ name: 'edit_file', arguments: {} });
+    expect(refused.isError).toBe(true);
+    expect(textOf(refused)).toBe(
+      'The tool "edit_file" is not available to this connection: it is connected as the agent "narrow" ' +
+        '(`Agents/narrow.agent`), which does not load it.',
+    );
+  });
+
+  it('Everything still answers an unknown tool as unknown', async () => {
+    const { mcp } = await harness();
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    const client = await connect(mcp, {});
+    expect((await client.listTools()).tools.map((t) => t.name)).toEqual(
+      expect.arrayContaining(['read_file', 'edit_file']),
+    );
+    expect(textOf(await client.callTool({ name: 'nope', arguments: {} }))).toBe('Unknown tool "nope".');
+  });
+
+  it('tells the agent at the handshake what it is connected as; Everything is told what it always was', async () => {
+    const { mcp } = await harness();
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    const narrowed = (await connect(mcp, { bearer: 'bevel_narrow', agentPath: 'Agents/narrow.agent' }, true)).getInstructions();
+    const everything = (await connect(mcp, {}, true)).getInstructions();
+    expect(narrowed).toBe(
+      `${everything}\n\nThis connection is connected as the agent "narrow" (\`Agents/narrow.agent\`): it loads only the ` +
+        'platform tools, connectors, skills and plugins that file lists, and of those only what you may read.',
+    );
+    expect(everything).not.toContain('connected as the agent');
+  });
+
+  it('two connections of one person made as different agents never share a built surface', async () => {
+    const { state, mcp } = await harness();
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    await (await connect(mcp, { bearer: 'bevel_narrow', agentPath: 'Agents/narrow.agent' })).listTools();
+    await (await connect(mcp, { bearer: 'bevel_narrow', agentPath: 'Agents/other.agent' })).listTools();
+    await (await connect(mcp, { bearer: 'bevel_narrow', agentPath: 'Agents/narrow.agent' })).listTools();
+    expect(state.builds).toBe(2);
+  });
+});
+
+describe('a connection whose agent file is gone', () => {
+  it('is served an empty listing carrying the reason, and every call — meta-tools too — answers it', async () => {
+    const { mcp } = await harness();
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    const client = await connect(mcp, { bearer: 'bevel_gone', agentPath: 'Agents/gone.agent' });
+    const listed = await client.listTools();
+    expect(listed.tools).toEqual([]);
+    expect(listed._meta).toEqual({ [CONNECTION_META_KEY]: GONE.unavailable });
+    for (const name of ['read_file', 'call_tool_chain']) {
+      const res = await client.callTool({ name, arguments: {} });
+      expect(res.isError).toBe(true);
+      expect(textOf(res)).toBe(GONE.unavailable);
+    }
+    const instructions = (await connect(mcp, { bearer: 'bevel_gone', agentPath: 'Agents/gone.agent' }, true)).getInstructions();
+    expect(instructions?.endsWith(GONE.unavailable!)).toBe(true);
+  });
+});

package/src/modules/mcp/__tests__/mcp.routes.connect-as.test.ts

@@ -0,0 +1,192 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { InternalTokenService } from '../../tool-auth/internal-token.service.js';
+import { createTokenVerifier } from '../../tool-auth/tool-auth.middleware.js';
+import type { IExternalApiKeyService } from '../../tool-auth/external-api-key.interface.js';
+import type { BevelOAuthProvider } from '../oauth/bevel-oauth-provider.js';
+import { NOT_AN_AGENT_CHOICE } from '../oauth/oauth-consent.routes.js';
+import { agentFile, agentScopeOver, inMemoryKb } from '../../agent-scope/__tests__/in-memory-kb.js';
+import { closeMountedRoutes, mountMcpRoutes } from './mcp-routes-harness.js';
+
+/**
+ * Connecting as an agent on the MCP router: the key-mint path takes the same
+ * "Connect as" choice the consent step does, the dialog is told the same
+ * agents, the local server's exchanged grant carries the connection's agent,
+ * and every MCP request hands the proxy the agent its credential connects as.
+ */
+
+const ADA = 'ada@example.com';
+const kb = inMemoryKb({
+  'Agents/ops.agent': agentFile('name: ops\ndescription: Watches the dashboards.'),
+  'Agents/secret.agent': agentFile('name: secret'),
+});
+kb.hidden.add('Agents/secret.agent');
+
+afterEach(async () => {
+  await closeMountedRoutes();
+  vi.restoreAllMocks();
+});
+
+function keyService() {
+  const mint = vi.fn(async (_userId: string, label: string, options?: { agentPath?: string }) => ({
+    plaintext: 'bevel_new',
+    summary: { id: 'k1', label, agentPath: options?.agentPath ?? null },
+  }));
+  return {
+    service: { looksLikeExternalApiKey: (t: string) => t.startsWith('bevel_'), mint } as unknown as IExternalApiKeyService,
+    mint,
+  };
+}
+
+const post = (url: string, body: unknown) =>
+  fetch(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-test-email': ADA },
+    body: JSON.stringify(body),
+  });
+
+describe('minting a connection key', () => {
+  it('as Everything: no choice is minted exactly as before', async () => {
+    const { service, mint } = keyService();
+    const base = await mountMcpRoutes({ externalApiKeyService: service, agents: agentScopeOver(kb) });
+    const res = await post(`${base}/api/mcp/external-api-keys`, { label: 'laptop' });
+    expect(res.status).toBe(200);
+    expect(mint).toHaveBeenCalledWith('user-A', 'laptop', {});
+  });
+
+  it('as an agent on offer: the key records its normalized path', async () => {
+    const { service, mint } = keyService();
+    const base = await mountMcpRoutes({ externalApiKeyService: service, agents: agentScopeOver(kb) });
+    const res = await post(`${base}/api/mcp/external-api-keys`, { label: 'pipeline', agentPath: 'Agents/ops.agent/' });
+    expect(res.status).toBe(200);
+    expect(mint).toHaveBeenCalledWith('user-A', 'pipeline', { agentPath: 'Agents/ops.agent' });
+    expect(((await res.json()) as { summary: { agentPath: string } }).summary.agentPath).toBe('Agents/ops.agent');
+  });
+
+  it.each([['Agents/secret.agent'], ['Agents/none.agent'], [7]])('refuses %s, minting nothing', async (agentPath) => {
+    const { service, mint } = keyService();
+    const base = await mountMcpRoutes({ externalApiKeyService: service, agents: agentScopeOver(kb) });
+    const res = await post(`${base}/api/mcp/external-api-keys`, { label: 'x', agentPath });
+    expect(res.status).toBe(400);
+    expect(await res.json()).toEqual({ error: NOT_AN_AGENT_CHOICE });
+    expect(mint).not.toHaveBeenCalled();
+  });
+
+  it('offers the same agents the consent step does', async () => {
+    const base = await mountMcpRoutes({ agents: agentScopeOver(kb) });
+    const res = await fetch(`${base}/api/mcp/agent-choices`, { headers: { 'x-test-email': ADA } });
+    expect(await res.json()).toEqual({
+      agents: [{ path: 'Agents/ops.agent', name: 'ops', description: 'Watches the dashboards.' }],
+    });
+  });
+
+  it('answers a failed listing as a failure, never as "no agents"', async () => {
+    const failing = { listChoices: async () => Promise.reject(new Error('clone failed')), choosable: async () => null };
+    const base = await mountMcpRoutes({ agents: failing });
+    const res = await fetch(`${base}/api/mcp/agent-choices`, { headers: { 'x-test-email': ADA } });
+    expect(res.status).toBe(500);
+    expect(await res.json()).not.toHaveProperty('agents');
+  });
+});
+
+describe('the local server’s exchanged grant', () => {
+  it("carries the connection's agent, so its calls narrow exactly as the hosted endpoint's", async () => {
+    const internalTokens = new InternalTokenService({ secret: 'test-secret' });
+    const oauth = {
+      looksLikeAccessToken: (t: string) => t.startsWith('bevel-mcp_'),
+      verifyAccessToken: async () => ({
+        extra: { userId: 'user-5', userEmail: ADA, connectionId: 'conn-9', agentPath: 'Agents/ops.agent' },
+        expiresAt: Math.floor(Date.now() / 1000) + 3600,
+      }),
+    } as unknown as BevelOAuthProvider;
+    const base = await mountMcpRoutes({
+      externalApiKeyService: { looksLikeExternalApiKey: () => false } as never,
+      internalTokens,
+      oauthProvider: oauth,
+    });
+    const res = await fetch(`${base}/api/mcp/local-token`, {
+      method: 'POST',
+      headers: { Authorization: 'Bearer bevel-mcp_grant' },
+    });
+    const { token } = (await res.json()) as { token: string };
+    const verify = createTokenVerifier({ looksLikeExternalApiKey: () => false } as never, internalTokens);
+    expect(await verify(token)).toEqual({
+      ok: true,
+      auth: { source: 'external', userId: 'user-5', connectionId: 'conn-9', agentPath: 'Agents/ops.agent', scope: 'write' },
+    });
+  });
+
+  it('an Everything grant mints the token it always did', async () => {
+    const internalTokens = new InternalTokenService({ secret: 'test-secret' });
+    const oauth = {
+      looksLikeAccessToken: (t: string) => t.startsWith('bevel-mcp_'),
+      verifyAccessToken: async () => ({
+        extra: { userId: 'user-5', userEmail: ADA, connectionId: 'conn-9', agentPath: null },
+        expiresAt: Math.floor(Date.now() / 1000) + 3600,
+      }),
+    } as unknown as BevelOAuthProvider;
+    const base = await mountMcpRoutes({
+      externalApiKeyService: { looksLikeExternalApiKey: () => false } as never,
+      internalTokens,
+      oauthProvider: oauth,
+    });
+    const res = await fetch(`${base}/api/mcp/local-token`, { method: 'POST', headers: { Authorization: 'Bearer bevel-mcp_g' } });
+    const { token } = (await res.json()) as { token: string };
+    expect(internalTokens.verify(token)).toEqual({ userId: 'user-5', externalProxy: true, connectionId: 'conn-9' });
+  });
+
+  it("a direct tool call reads the connection's CURRENT choice: a re-consent reaches a token minted before it", async () => {
+    const internalTokens = new InternalTokenService({ secret: 'test-secret' });
+    const keys = { looksLikeExternalApiKey: () => false } as never;
+    let current: { agentPath: string | null } | null = { agentPath: 'Agents/ops.agent' };
+    const verify = createTokenVerifier(keys, internalTokens, undefined, {
+      liveConnectionChoice: async (id) => (id === 'conn-9' ? current : null),
+    });
+    // Minted as Everything, served as the agent chosen since.
+    const everything = internalTokens.mint({ userId: 'user-5', externalProxy: true, connectionId: 'conn-9' }, 60_000);
+    expect(await verify(everything)).toEqual({
+      ok: true,
+      auth: { source: 'external', userId: 'user-5', connectionId: 'conn-9', agentPath: 'Agents/ops.agent', scope: 'write' },
+    });
+    // Minted as an agent, served as Everything once the person chose it.
+    current = { agentPath: null };
+    const asAgent = internalTokens.mint(
+      { userId: 'user-5', externalProxy: true, connectionId: 'conn-9', agentPath: 'Agents/ops.agent' },
+      60_000,
+    );
+    expect(await verify(asAgent)).toEqual({
+      ok: true,
+      auth: { source: 'external', userId: 'user-5', connectionId: 'conn-9', scope: 'write' },
+    });
+  });
+
+  it("refuses a direct tool call through a revoked connection's token, whatever the token says it connects as", async () => {
+    const internalTokens = new InternalTokenService({ secret: 'test-secret' });
+    const keys = { looksLikeExternalApiKey: () => false } as never;
+    const verify = createTokenVerifier(keys, internalTokens, undefined, { liveConnectionChoice: async () => null });
+    const token = internalTokens.mint(
+      { userId: 'user-5', externalProxy: true, connectionId: 'conn-9', agentPath: 'Agents/ops.agent' },
+      60_000,
+    );
+    expect(await verify(token)).toEqual({ ok: false, status: 401, message: 'Access for this agent was revoked' });
+  });
+});
+
+describe('an MCP request', () => {
+  it("hands the proxy the agent its credential connects as — and nothing for Everything", async () => {
+    const createRequestServer = vi.fn(async () => {
+      throw new Error('stop here');
+    });
+    const base = await mountMcpRoutes({ mcpService: { createRequestServer } });
+    const call = (headers: Record<string, string>) =>
+      fetch(`${base}/api/mcp`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', ...headers },
+        body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }),
+      });
+    await call({ 'x-test-agent-path': 'Agents/ops.agent' });
+    await call({});
+    const callers = createRequestServer.mock.calls.map((c) => (c as unknown[])[0] as Record<string, unknown>);
+    expect(callers[0]).toMatchObject({ userId: 'user-A', agentPath: 'Agents/ops.agent' });
+    expect(callers[1]).not.toHaveProperty('agentPath');
+  });
+});