feat(mcp-server): support proxy and regional placement (#57)

Co-authored-by: Codex <codex@openai.com>

Author: AbdulRashidReshamwala

charts/platform/templates/mcp-server.yaml

@@ -39,6 +39,18 @@ spec:
               value: {{ $mcp.sessionBlockSeconds | quote }}
             - name: MCP_OPERATION_LEASE_SECONDS
               value: {{ $mcp.operationLeaseSeconds | quote }}
+            {{- if .Values.controlPlane.regions }}
+            {{- $mcpRegionNames := list }}
+            {{- range .Values.controlPlane.regions }}
+            {{- if not .x402Only }}
+            {{- $mcpRegionNames = append $mcpRegionNames .name }}
+            {{- end }}
+            {{- end }}
+            {{- if $mcpRegionNames }}
+            - name: MCP_AVAILABLE_REGIONS
+              value: {{ join "," $mcpRegionNames | quote }}
+            {{- end }}
+            {{- end }}
             - name: MCP_BILLING_PROVIDER
               value: {{ $mcp.billing.provider | quote }}
             {{- if eq $mcp.billing.provider "external" }}

services/mcp-server/README.md

@@ -37,6 +37,11 @@ implementation.
 | `end_browser_session` | – | End early |
 | `list_browser_sessions` | – | Recent sessions for this identity |
 
+`create_browser_session` accepts optional `regions` in nearest-first fallback
+order and an optional two-letter `proxy_country`. Proxy URLs and credentials are
+never accepted from MCP callers; the selected country uses the deployment-owned
+proxy preset.
+
 ## Billing is an extension point
 
 This service performs the **browser** effect, so it owns operation idempotency
@@ -142,6 +147,7 @@ Bring your own provider by implementing the interface and wiring it in
 | `MCP_TOKEN_SIGNING_KEY` | dev key | Signs tokens and derives subjects; rotating it invalidates both |
 | `MCP_SESSION_TTL_SECONDS` | `600` | Fixed block of browser time per billed operation |
 | `MCP_OPERATION_LEASE_SECONDS` | `120` | When one retry may recover a crashed operation |
+| `MCP_AVAILABLE_REGIONS` | – | Comma-separated region names advertised for nearest-first placement |
 | `MCP_BILLING_PROVIDER` | `none` | `none` or `external` |
 | `MCP_BILLING_BASE_URL` | – | Billing service base URL (external only) |
 | `MCP_BILLING_AUTH_TOKEN` | – | Bearer token for that service |

services/mcp-server/src/config.ts

@@ -9,6 +9,10 @@ function num(name: string, fallback: number): number {
   return Number.isFinite(parsed) ? parsed : fallback;
 }
 
+function list(name: string): string[] {
+  return [...new Set(env(name).split(',').map((value) => value.trim()).filter(Boolean))];
+}
+
 function databaseUrl(): string {
   const direct = env('DATABASE_URL');
   if (direct) return direct;
@@ -39,6 +43,8 @@ export const McpConfig = {
   sessionTtlSeconds: num('MCP_SESSION_TTL_SECONDS', 600),
   /** How long one worker owns an operation before a retry may recover it. */
   operationLeaseSeconds: num('MCP_OPERATION_LEASE_SECONDS', 120),
+  /** Region names advertised to MCP clients for nearest-first placement. */
+  availableRegions: list('MCP_AVAILABLE_REGIONS'),
   /**
    * Billing. `none` (default) meters nothing — the right choice for
    * self-hosters. `external` delegates balance/reserve/commit/release to an

services/mcp-server/src/mcp.test.ts

@@ -124,6 +124,21 @@ describe('billing boundary', () => {
     expect((response as any).result.structuredContent.error).toBe('billing_unavailable');
   });
 
+  test('invalid placement is rejected before reserving credit', async () => {
+    const billing = new RecordingBilling();
+    const response = await handleRpc(ctx(billing), {
+      jsonrpc: '2.0',
+      id: 70,
+      method: 'tools/call',
+      params: {
+        name: 'create_browser_session',
+        arguments: { purpose: 'x', idempotency_key: 'bad-placement', regions: [], proxy_country: 'USA' },
+      },
+    });
+    expect((response as any).result.structuredContent.error).toBe('invalid_request');
+    expect(billing.calls).toEqual([]);
+  });
+
   test('a refused reservation releases the claim so the same key can be retried', async () => {
     const billing = new RecordingBilling({ ok: false, reason: 'insufficient_credit' });
     const context = ctx(billing);

services/mcp-server/src/mcp.ts

@@ -28,7 +28,7 @@ export async function handleRpc(ctx: ToolContext, request: JsonRpcRequest): Prom
         capabilities: { tools: { listChanged: false } },
         serverInfo: { name: 'popcorn', title: 'Popcorn browser sessions', version: '0.1.0' },
         instructions:
-          'Popcorn runs isolated, disposable cloud browsers. Call create_browser_session for a fixed block of browser time, then hand the live-view URL to the human for any login. If this deployment meters usage, get_balance reports remaining credit and a refused operation returns next_action telling the human how to obtain more.',
+          'Popcorn runs isolated, disposable cloud browsers. Call create_browser_session for a fixed block of browser time, preferring regions closest to the human and listing fallbacks nearest-first. Use proxy_country only when the task needs a particular network exit country. Then hand the live-view URL to the human for any login. If this deployment meters usage, get_balance reports remaining credit and a refused operation returns next_action telling the human how to obtain more.',
       });
 
     case 'notifications/initialized':

services/mcp-server/src/popcorn.ts

@@ -45,6 +45,26 @@ export function toSessionView(session: PopcornSession): SessionView {
 
 export type PopcornResult<T> = { ok: true; data: T } | { ok: false; status: number; error: string };
 
+export type CreateSessionInput = {
+  sessionId: string;
+  ttlSeconds: number;
+  metadata: Record<string, unknown>;
+  /** Popcorn region names, ordered nearest-first with later entries as fallback. */
+  regions?: string[];
+  /** Deployment-managed proxy exit country; callers never provide proxy URLs. */
+  proxyCountry?: string;
+};
+
+export function createSessionRequestBody(input: CreateSessionInput): Record<string, unknown> {
+  return {
+    sessionId: input.sessionId,
+    ttlSeconds: input.ttlSeconds,
+    metadata: input.metadata,
+    ...(input.regions ? { regions: input.regions } : {}),
+    ...(input.proxyCountry ? { proxy: { country: input.proxyCountry } } : {}),
+  };
+}
+
 function authHeader(): Record<string, string> {
   return {
     authorization: `Bearer ${McpConfig.controlPlaneClientId}:${McpConfig.controlPlaneClientSecret}`,
@@ -70,14 +90,10 @@ async function call<T>(path: string, init: RequestInit): Promise<PopcornResult<T
   return { ok: true, data: body as T };
 }
 
-export function createSession(input: {
-  sessionId: string;
-  ttlSeconds: number;
-  metadata: Record<string, unknown>;
-}): Promise<PopcornResult<PopcornSession>> {
+export function createSession(input: CreateSessionInput): Promise<PopcornResult<PopcornSession>> {
   return call<PopcornSession>('/v1/sessions', {
     method: 'POST',
-    body: JSON.stringify({ sessionId: input.sessionId, ttlSeconds: input.ttlSeconds, metadata: input.metadata }),
+    body: JSON.stringify(createSessionRequestBody(input)),
   });
 }
 

services/mcp-server/src/tools.ts

@@ -7,6 +7,13 @@ import type { McpStore } from './store';
 export type ToolContext = { store: McpStore; subject: string; billing: BillingProvider };
 export type ToolResult = { content: Array<{ type: 'text'; text: string }>; isError?: boolean; structuredContent?: unknown };
 
+const regionItems = {
+  type: 'string',
+  minLength: 1,
+  maxLength: 64,
+  ...(McpConfig.availableRegions.length ? { enum: McpConfig.availableRegions } : {}),
+};
+
 function ok(data: unknown): ToolResult {
   return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }], structuredContent: data };
 }
@@ -152,7 +159,7 @@ export const TOOL_DEFINITIONS = [
   {
     name: 'create_browser_session',
     description:
-      `Start one isolated Popcorn browser session. One operation buys one fixed block of ${McpConfig.sessionTtlSeconds} seconds; the duration is not negotiable. Returns session id, live-view URL for the human, CDP URL for the agent, and expiry. The browser is fresh and isolated: no local Chrome profile, cookies, or saved passwords.`,
+      `Start one isolated Popcorn browser session. One operation buys one fixed block of ${McpConfig.sessionTtlSeconds} seconds; the duration is not negotiable. Prefer a region close to the human to reduce live-view and automation latency. Returns session id, live-view URL for the human, CDP URL for the agent, selected region, and expiry. The browser is fresh and isolated: no local Chrome profile, cookies, or saved passwords.`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -161,6 +168,20 @@ export const TOOL_DEFINITIONS = [
           type: 'string',
           description: 'Reuse the same key when retrying: you get back the same session, never a second one.',
         },
+        regions: {
+          type: 'array',
+          minItems: 1,
+          maxItems: 8,
+          items: regionItems,
+          description:
+            `Optional Popcorn region names ordered closest-to-human first; later entries are allocation fallbacks. Omit to use the deployment default order.${McpConfig.availableRegions.length ? ` Available regions: ${McpConfig.availableRegions.join(', ')}.` : ''}`,
+        },
+        proxy_country: {
+          type: 'string',
+          pattern: '^[A-Za-z]{2}$',
+          description:
+            'Optional ISO 3166-1 alpha-2 country code for a deployment-managed proxy exit (for example US or IN). This selects a country, never a proxy URL.',
+        },
       },
       required: ['purpose', 'idempotency_key'],
       additionalProperties: false,
@@ -251,6 +272,33 @@ export async function callTool(ctx: ToolContext, name: string, args: Record<stri
       if (!purpose) return fail({ error: 'invalid_request', message: 'purpose is required' });
       const key = idempotencyKey(args.idempotency_key);
       if (!key) return fail({ error: 'invalid_request', message: 'idempotency_key is required (max 200 characters)' });
+      let regions: string[] | undefined;
+      if (args.regions !== undefined) {
+        if (!Array.isArray(args.regions) || args.regions.length < 1 || args.regions.length > 8
+          || args.regions.some((region: unknown) => typeof region !== 'string' || !region.trim() || region.trim().length > 64)) {
+          return fail({
+            error: 'invalid_request',
+            message: 'regions must contain 1-8 Popcorn region names ordered nearest-first',
+          });
+        }
+        regions = [...new Set(args.regions.map((region: string) => region.trim()))];
+        const unknown = regions.find((region) => McpConfig.availableRegions.length
+          && !McpConfig.availableRegions.includes(region));
+        if (unknown) {
+          return fail({
+            error: 'invalid_request',
+            message: `unknown region: ${unknown}`,
+            available_regions: McpConfig.availableRegions,
+          });
+        }
+      }
+      let proxyCountry: string | undefined;
+      if (args.proxy_country !== undefined) {
+        if (typeof args.proxy_country !== 'string' || !/^[A-Za-z]{2}$/.test(args.proxy_country.trim())) {
+          return fail({ error: 'invalid_request', message: 'proxy_country must be a two-letter ISO country code' });
+        }
+        proxyCountry = args.proxy_country.trim().toUpperCase();
+      }
       const ref = `session:${ctx.subject}:${key}`;
       const sessionId = sessionIdForOperation(ref);
 
@@ -268,6 +316,8 @@ export async function callTool(ctx: ToolContext, name: string, args: Record<stri
         sessionId,
         ttlSeconds: McpConfig.sessionTtlSeconds,
         metadata: { subject: ctx.subject, purpose },
+        regions,
+        proxyCountry,
       });
       // A recovered operation uses the same deterministic id. The normal API
       // reports the already-created effect as 409, so fetch and replay it.
@@ -300,6 +350,7 @@ export async function callTool(ctx: ToolContext, name: string, args: Record<stri
         cdp_url: view.agentCdpUrl,
         expires_at: view.expiresAt,
         region: view.region,
+        proxy_country: proxyCountry ?? null,
         isolation: 'Fresh isolated browser. No local Chrome profile, cookies, or saved passwords.',
         human_handoff: 'Send live_view_url to the human for any login; do not ask them for credentials.',
         // False means the session is live but its usage has not been confirmed

services/mcp-server/src/wire.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { toSessionView } from './popcorn';
+import { createSessionRequestBody, toSessionView } from './popcorn';
 import { RESOURCE_URI, issueAccessToken, resourceMatches, verifyAccessToken } from './oauth';
 
 describe('control-plane wire contract', () => {
@@ -18,6 +18,27 @@ describe('control-plane wire contract', () => {
     expect(view.agentCdpUrl).toBe('wss://gw/cdp-internal/s/internal-token/');
     expect(toSessionView({ sessionId: 's', cdpUrl: 'wss://gw/cdp/s/restricted-token/' }).agentCdpUrl).toBeNull();
   });
+
+  test('session placement forwards nearest-first regions and a managed proxy country', () => {
+    expect(createSessionRequestBody({
+      sessionId: 's',
+      ttlSeconds: 600,
+      metadata: { purpose: 'test' },
+      regions: ['asia-south1', 'us-central1'],
+      proxyCountry: 'IN',
+    })).toEqual({
+      sessionId: 's',
+      ttlSeconds: 600,
+      metadata: { purpose: 'test' },
+      regions: ['asia-south1', 'us-central1'],
+      proxy: { country: 'IN' },
+    });
+  });
+
+  test('session placement omits proxy and region fields when not requested', () => {
+    expect(createSessionRequestBody({ sessionId: 's', ttlSeconds: 600, metadata: {} }))
+      .toEqual({ sessionId: 's', ttlSeconds: 600, metadata: {} });
+  });
 });
 
 describe('resource binding', () => {