feat(mcp): Carry regionUrl on constraints and unify regional routing (#907)

Resolve and carry `regionUrl` on MCP session constraints so it is
filtered from tool schemas and auto-injected like `organizationSlug`
when it is a non-empty string. Hosted verification already loads
`links.regionUrl` from the org API; OAuth can also persist
`constraintRegionUrl` when the grant resource scopes `/mcp/:org`, and
the worker merges that into URL constraints when the request path org
matches the token scope (defense-in-depth when cache or verification
paths differ).

Stdio now performs a one-time `getOrganization` when both an org slug
and access token are configured, so CLI org-scoped sessions populate
`constraints.regionUrl` the same way.

Trace, profile, and replay detail tools share
`resolveRegionUrlForOrganization`; `get_sentry_resource` forwards
`constraints.regionUrl` into composed handlers because those calls
bypass MCP parameter merge. Constraint helpers gain documentation and
tests for `regionUrl` as a string constraint.

OAuth `resource` URL parsing is extracted to `resource-scope.ts` for
reuse in authorize and callback. Cloudflare constraint verification
caching is adjusted for org-only keys alongside existing project-scoped
entries.

Reviewers should sanity-check the OAuth merge conditions in
`mcp-handler.ts` and KV cache semantics in `constraint-utils.ts` for
multi-tenant isolation.

---------

Co-authored-by: Composer <composer@cursor.com>
Co-authored-by: Codex CLI Agent <noreply@openai.com>

Author: 3 people

packages/mcp-cloudflare/src/server/lib/constraint-utils.test.ts

@@ -177,7 +177,7 @@ describe("verifyConstraintsAccess", () => {
       // Verify cache was checked
       expect(mockKV.get).toHaveBeenCalledOnce();
       expect(mockKV.get).toHaveBeenCalledWith(
-        "caps:v1:user-123:sentry.io:sentry-mcp-evals:cloudflare-mcp",
+        "caps:v1:user-123:sentry.io:sentry-mcp-evals:project:cloudflare-mcp",
         "json",
       );
 
@@ -222,7 +222,7 @@ describe("verifyConstraintsAccess", () => {
       // Verify cache was written with correct key and TTL
       expect(mockKV.put).toHaveBeenCalledOnce();
       expect(mockKV.put).toHaveBeenCalledWith(
-        "caps:v1:user-456:sentry.io:sentry-mcp-evals:cloudflare-mcp",
+        "caps:v1:user-456:sentry.io:sentry-mcp-evals:project:cloudflare-mcp",
         expect.any(String),
         { expirationTtl: 900 },
       );
@@ -294,8 +294,13 @@ describe("verifyConstraintsAccess", () => {
       expect(mockKV.put).toHaveBeenCalledOnce();
     });
 
-    it("does not use cache for org-only verification", async () => {
-      const mockKV = createMockKV({ getResult: cachedData });
+    it("uses cache for org-only verification", async () => {
+      const orgOnlyCached: CachedConstraints = {
+        regionUrl: "https://us.sentry.io",
+        projectCapabilities: null,
+        cachedAt: Date.now(),
+      };
+      const mockKV = createMockKV({ getResult: orgOnlyCached });
       const cache: CacheOptions = {
         kv: mockKV,
         userId: "user-org-only",
@@ -307,10 +312,82 @@ describe("verifyConstraintsAccess", () => {
       );
 
       expect(result.ok).toBe(true);
+      if (result.ok) {
+        expect(result.constraints).toEqual({
+          organizationSlug: "sentry-mcp-evals",
+          projectSlug: null,
+          regionUrl: "https://us.sentry.io",
+          projectCapabilities: null,
+        });
+      }
 
-      // Cache should not be checked for org-only verification
-      expect(mockKV.get).not.toHaveBeenCalled();
+      expect(mockKV.get).toHaveBeenCalledOnce();
+      expect(mockKV.get).toHaveBeenCalledWith(
+        "caps:v1:user-org-only:sentry.io:sentry-mcp-evals:org",
+        "json",
+      );
       expect(mockKV.put).not.toHaveBeenCalled();
     });
+
+    it("uses distinct cache keys for org-only and '__org__' project constraints", async () => {
+      const mockKV = createMockKV({ getResult: cachedData });
+      const cache: CacheOptions = {
+        kv: mockKV,
+        userId: "user-sentinel",
+      };
+
+      const orgOnlyResult = await verifyConstraintsAccess(
+        { organizationSlug: "sentry-mcp-evals", projectSlug: null },
+        { accessToken: token, sentryHost: host, cache },
+      );
+      const projectResult = await verifyConstraintsAccess(
+        { organizationSlug: "sentry-mcp-evals", projectSlug: "__org__" },
+        { accessToken: token, sentryHost: host, cache },
+      );
+
+      expect(orgOnlyResult.ok).toBe(true);
+      expect(projectResult.ok).toBe(true);
+      expect(mockKV.get).toHaveBeenNthCalledWith(
+        1,
+        "caps:v1:user-sentinel:sentry.io:sentry-mcp-evals:org",
+        "json",
+      );
+      expect(mockKV.get).toHaveBeenNthCalledWith(
+        2,
+        "caps:v1:user-sentinel:sentry.io:sentry-mcp-evals:project:__org__",
+        "json",
+      );
+    });
+
+    it("writes KV cache after org-only verification on miss", async () => {
+      const mockKV = createMockKV({ getResult: null });
+      const cache: CacheOptions = {
+        kv: mockKV,
+        userId: "user-org-cache-write",
+      };
+
+      const result = await verifyConstraintsAccess(
+        { organizationSlug: "sentry-mcp-evals", projectSlug: null },
+        { accessToken: token, sentryHost: host, cache },
+      );
+
+      expect(result.ok).toBe(true);
+      expect(mockKV.get).toHaveBeenCalledOnce();
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      expect(mockKV.put).toHaveBeenCalledOnce();
+      expect(mockKV.put).toHaveBeenCalledWith(
+        "caps:v1:user-org-cache-write:sentry.io:sentry-mcp-evals:org",
+        expect.any(String),
+        { expirationTtl: 900 },
+      );
+      const parsed = JSON.parse(
+        vi.mocked(mockKV.put).mock.calls[0][1] as string,
+      );
+      expect(parsed).toMatchObject({
+        regionUrl: "https://us.sentry.io",
+        projectCapabilities: null,
+        cachedAt: expect.any(Number),
+      });
+    });
   });
 });

packages/mcp-cloudflare/src/server/lib/constraint-utils.ts

@@ -14,7 +14,8 @@ const CACHE_KEY_VERSION = "v1";
  */
 export type CachedConstraints = {
   regionUrl: string | null;
-  projectCapabilities: ProjectCapabilities;
+  /** Populated when a project constraint was verified; null for org-only cache entries. */
+  projectCapabilities: ProjectCapabilities | null;
   cachedAt: number;
 };
 
@@ -28,15 +29,20 @@ export type CacheOptions = {
 
 /**
  * Build a cache key for constraints verification.
- * Format: caps:v1:{userId}:{sentryHost}:{organizationSlug}:{projectSlug}
+ * Format: caps:v1:{userId}:{sentryHost}:{organizationSlug}:{scopeKey}
+ * scopeKey is "org" for org-only entries or "project:{slug}" for project-scoped entries.
  */
 function buildCacheKey(
   userId: string,
   sentryHost: string,
   organizationSlug: string,
-  projectSlug: string,
+  projectSlug: string | null | undefined,
 ): string {
-  return `caps:${CACHE_KEY_VERSION}:${userId}:${sentryHost}:${organizationSlug}:${projectSlug}`;
+  const normalizedProjectSlug = projectSlug?.trim();
+  const scopeKey = normalizedProjectSlug
+    ? `project:${normalizedProjectSlug}`
+    : "org";
+  return `caps:${CACHE_KEY_VERSION}:${userId}:${sentryHost}:${organizationSlug}:${scopeKey}`;
 }
 
 /**
@@ -149,10 +155,10 @@ export async function verifyConstraintsAccess(
     };
   }
 
-  // Check cache if project constraints are requested and cache is available
-  // Cache key includes userId to ensure per-user isolation
+  // Check KV cache when available (org-only and org+project keys).
+  // Cache key includes userId to ensure per-user isolation.
   let cacheKey: string | null = null;
-  if (projectSlug && cache) {
+  if (cache) {
     cacheKey = buildCacheKey(
       cache.userId,
       sentryHost,
@@ -161,12 +167,11 @@ export async function verifyConstraintsAccess(
     );
     const cached = await getCachedConstraints(cache.kv, cacheKey);
     if (cached) {
-      // Cache hit - return cached constraints without API calls
       return {
         ok: true,
         constraints: {
           organizationSlug,
-          projectSlug,
+          projectSlug: projectSlug || null,
           regionUrl: cached.regionUrl,
           projectCapabilities: cached.projectCapabilities,
         },
@@ -254,12 +259,12 @@ export async function verifyConstraintsAccess(
     }
   }
 
-  // Cache successful verification results for project constraints
-  // Fire-and-forget write - don't block response on cache update
-  if (cacheKey && projectCapabilities) {
+  // Cache: org-only after org fetch; org+project only when project verification
+  // succeeded (skip caching on project timeout so the next request can retry).
+  if (cacheKey && (!projectSlug || projectCapabilities !== null)) {
     void setCachedConstraints(cache!.kv, cacheKey, {
       regionUrl: regionUrl || null,
-      projectCapabilities,
+      projectCapabilities: projectSlug ? projectCapabilities : null,
       cachedAt: Date.now(),
     });
   }

packages/mcp-cloudflare/src/server/lib/mcp-handler.test.ts

@@ -9,6 +9,8 @@ interface OAuthProps {
   accessToken: string;
   refreshToken: string;
   grantedSkills: string[];
+  constraintOrganizationSlug?: string | null;
+  constraintProjectSlug?: string | null;
 }
 
 const DEFAULT_OAUTH_PROPS: OAuthProps = {
@@ -248,6 +250,68 @@ describe("MCP Handler", () => {
       expect(response.status).toBe(404);
       expect(await response.text()).toContain("not found");
     });
+
+    it("returns 403 when the token is org-scoped but the MCP URL uses a different organization", async () => {
+      const request = createMcpRequest(
+        "initialize",
+        {
+          protocolVersion: "2024-11-05",
+          capabilities: {},
+          clientInfo: { name: "test-client", version: "1.0.0" },
+        },
+        { path: "/mcp/other-org" },
+      );
+      const ctx = createMcpContext({
+        constraintOrganizationSlug: "my-org",
+      });
+
+      const response = await mcpHandler.fetch!(request, createTestEnv(), ctx);
+
+      expect(response.status).toBe(403);
+      expect(await response.text()).toContain("scoped to an organization");
+    });
+
+    it("returns 403 when the token is project-scoped but the MCP URL uses a different project", async () => {
+      const request = createMcpRequest(
+        "initialize",
+        {
+          protocolVersion: "2024-11-05",
+          capabilities: {},
+          clientInfo: { name: "test-client", version: "1.0.0" },
+        },
+        { path: "/mcp/my-org/wrong-project" },
+      );
+      const ctx = createMcpContext({
+        constraintOrganizationSlug: "my-org",
+        constraintProjectSlug: "expected-project",
+      });
+
+      const response = await mcpHandler.fetch!(request, createTestEnv(), ctx);
+
+      expect(response.status).toBe(403);
+      expect(await response.text()).toContain("scoped to a project");
+    });
+
+    it("returns 403 when the token is project-scoped but the MCP URL omits the project segment", async () => {
+      const request = createMcpRequest(
+        "initialize",
+        {
+          protocolVersion: "2024-11-05",
+          capabilities: {},
+          clientInfo: { name: "test-client", version: "1.0.0" },
+        },
+        { path: "/mcp/my-org" },
+      );
+      const ctx = createMcpContext({
+        constraintOrganizationSlug: "my-org",
+        constraintProjectSlug: "my-project",
+      });
+
+      const response = await mcpHandler.fetch!(request, createTestEnv(), ctx);
+
+      expect(response.status).toBe(403);
+      expect(await response.text()).toContain("scoped to a project");
+    });
   });
 
   describe("MCP protocol", () => {

packages/mcp-cloudflare/src/server/lib/mcp-handler.ts

@@ -220,6 +220,23 @@ const mcpHandler: ExportedHandler<Env> = {
       );
     }
 
+    const tokenOrg = rawProps.constraintOrganizationSlug?.trim() || null;
+    const tokenProject = rawProps.constraintProjectSlug?.trim() || null;
+    if (tokenOrg && organizationSlug !== tokenOrg) {
+      return new Response(
+        "This token is scoped to an organization. Use the MCP URL for the organization you authorized.",
+        { status: 403 },
+      );
+    }
+    if (tokenProject) {
+      if (!projectSlug || projectSlug !== tokenProject) {
+        return new Response(
+          "This token is scoped to a project. Use the MCP URL that includes that project (for example /mcp/<org>/<project>).",
+          { status: 403 },
+        );
+      }
+    }
+
     // Verify user has access to the requested org/project
     // Cache verification results in KV to avoid repeated API calls
     const verification = await verifyConstraintsAccess(
@@ -240,13 +257,15 @@ const mcpHandler: ExportedHandler<Env> = {
       });
     }
 
+    const constraints = verification.constraints;
+
     // Build complete ServerContext from OAuth props + verified constraints
     const serverContext: ServerContext = {
       userId,
       clientId,
       accessToken,
       grantedSkills: validSkills,
-      constraints: verification.constraints,
+      constraints,
       sentryHost,
       mcpUrl: env.MCP_URL,
       agentMode: isAgentMode,

packages/mcp-cloudflare/src/server/oauth/resource-scope.ts

@@ -0,0 +1,38 @@
+/**
+ * Parse RFC 8707 `resource` URLs that scope this MCP deployment to an org/project.
+ * Example: https://example.com/mcp/my-org/backend
+ */
+export function parseResourceMcpConstraints(
+  resource: string | null | undefined,
+): { organizationSlug: string; projectSlug: string | null } | null {
+  if (!resource) {
+    return null;
+  }
+
+  try {
+    const { pathname } = new URL(resource);
+    const pathSegments = pathname.split("/").filter(Boolean);
+
+    if (pathSegments[0] !== "mcp") {
+      return null;
+    }
+
+    if (pathSegments.length === 2) {
+      return {
+        organizationSlug: pathSegments[1],
+        projectSlug: null,
+      };
+    }
+
+    if (pathSegments.length === 3) {
+      return {
+        organizationSlug: pathSegments[1],
+        projectSlug: pathSegments[2],
+      };
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}