@noodleseed/agent-kit 0.48.2 → 0.50.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noodleseed/agent-kit",
-  "version": "0.48.2",
+  "version": "0.50.0",
   "private": false,
   "description": "Self-checking, self-updating agent skills for the Noodle Seed CLI. Authored in this repo by @noodle-borg/agent-kit; this is the published, independently-versioned canonical skills artifact the CLI fetches and verifies.",
   "license": "Apache-2.0",

package/skills/claude-code/SKILL.md

@@ -3,7 +3,7 @@ name: noodle-seed
 description: "Use when building, validating, testing, deploying, or operating a local or hosted Noodle Seed MCP server or app authored in TypeScript with the noodle CLI."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:cd6ca0d915e6acb9 -->
+<!-- noodle-skill version:0.50.0 hash:cd6ca0d915e6acb9 -->
 
 # Noodle Seed
 

package/skills/claude-code/authoring-mcp-servers/SKILL.md

@@ -3,7 +3,7 @@ name: authoring-mcp-servers
 description: "Use when creating or extending a headless Noodle Seed MCP server, tool, resource, prompt, or typed model-facing capability."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:0b2fd8c7e43fc69f -->
+<!-- noodle-skill version:0.50.0 hash:0b2fd8c7e43fc69f -->
 
 # authoring-mcp-servers
 

package/skills/claude-code/building-mcp-apps/SKILL.md

@@ -3,7 +3,7 @@ name: building-mcp-apps
 description: "Use when a Noodle Seed MCP App, widget, interactive card, visual interaction, or host-visible UI is the primary requested outcome."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:f7fa54992c8d7692 -->
+<!-- noodle-skill version:0.50.0 hash:f7fa54992c8d7692 -->
 
 # building-mcp-apps
 

package/skills/claude-code/connecting-apis-to-mcp/SKILL.md

@@ -3,7 +3,7 @@ name: connecting-apis-to-mcp
 description: "Use when credentials, an API URL, an OpenAPI document, or an observed response must become real Noodle Seed MCP behavior."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:1e86b8704f407bd3 -->
+<!-- noodle-skill version:0.50.0 hash:1e86b8704f407bd3 -->
 
 # connecting-apis-to-mcp
 

package/skills/claude-code/debugging-mcp-delivery/SKILL.md

@@ -3,7 +3,7 @@ name: debugging-mcp-delivery
 description: "Use when an existing Noodle Seed MCP project has a concrete validation, runtime, connector, App, host, deployment, or production failure."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:aa715bae12041d7c -->
+<!-- noodle-skill version:0.50.0 hash:aa715bae12041d7c -->
 
 # debugging-mcp-delivery
 

package/skills/claude-code/deploying-mcp-services/SKILL.md

@@ -3,7 +3,7 @@ name: deploying-mcp-services
 description: "Use when the user explicitly requests a Noodle Seed hosted link, configuration write, deployment, access change, rollback, or connection write."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:93e735b7ffb45df1 -->
+<!-- noodle-skill version:0.50.0 hash:93e735b7ffb45df1 -->
 
 # deploying-mcp-services
 

package/skills/claude-code/designing-mcp-products/SKILL.md

@@ -3,7 +3,7 @@ name: designing-mcp-products
 description: "Use when a Noodle Seed MCP product idea needs conversational fit, user benefit, scope, interaction, or evidence design before implementation."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:76cce86729cffbee -->
+<!-- noodle-skill version:0.50.0 hash:76cce86729cffbee -->
 
 # designing-mcp-products
 

package/skills/claude-code/embedding-mcp-assistants/SKILL.md

@@ -3,7 +3,7 @@ name: embedding-mcp-assistants
 description: "Use when embedding a Noodle assistant into an existing SaaS or web application with browser, identity, session, and credential boundaries."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:cc54a67f21c0ecdb -->
+<!-- noodle-skill version:0.50.0 hash:cc54a67f21c0ecdb -->
 
 # embedding-mcp-assistants
 

package/skills/claude-code/examples/customer-auth/README.md

@@ -15,7 +15,9 @@ surface for org discovery:
 
 - `list_my_organizations` lists the NoodleSeed.com organizations the signed-in customer belongs to (no
   arguments — the org set comes from the verified customer session).
-- `list_org_apps` lists apps for one of those organizations through the dev app API.
+- `list_org_apps` lists apps for one of those organizations through the dev app API. It is visible and
+  callable only when the verified customer has the `org_apps:read` scope and either the `org_admin` or
+  `org_member` role.
 
 The two tools chain: `list_my_organizations` surfaces the `org_id`s the customer can act on, and
 `list_org_apps` takes one of those `org_id`s. There is no NoodleSeed-specific SDK helper. The downstream API
@@ -34,6 +36,19 @@ bounded read-only GET checks and never register a client. A successful
 `noodle deploy --access customers` reports the same findings as nonblocking warnings; the application team
 repairs the issuer rather than adding a Noodle OAuth proxy.
 
+Adding the embedded assistant does not choose or rewrite MCP customer auth. Inspect the exact active
+deployment before changing configuration:
+
+```sh
+noodle deployments list --org <org> --app <app> --env <env> --json
+```
+
+This Firebase bridge intentionally advertises the Noodle authorization server. A direct or federated
+replacement must advertise its configured tenant issuer. If the exact active direct/federated `customers`
+deployment instead advertises the platform issuer, report `customer_auth_state_inconsistent` with only the
+endpoint, deployment ID, server version, and sanitized protected-resource metadata. Do not share tokens or
+secrets, proxy or rewrite metadata, rotate credentials, or redeploy repeatedly to conceal the mismatch.
+
 During MCP OAuth login, Noodle Cloud hosts the Firebase bridge page at
 `https://cloud.noodleseed.dev/oauth/customer/firebase/authorize`. The customer app does not add an
 authorization route. The SaaS operator only configures Firebase Auth to allow the Noodle Cloud origin, and
@@ -61,9 +76,10 @@ auth: customerAuth.firebase({
     email: 'email',
     name: 'name',
     tenant: 'firebase.tenant',
-    orgs: 'claims.orgs',
-    roles: 'claims.roles',
-  },
+        orgs: 'claims.orgs',
+        roles: 'claims.roles',
+        scopes: 'claims.scopes',
+      },
 }),
 ```
 
@@ -79,6 +95,24 @@ auth: {
 },
 ```
 
+The mapped `roles` and `scopes` paths are read only after Firebase verifies the ID token. The restricted
+tool declares its rule beside the rest of its public contract:
+
+```ts
+tool('list_org_apps', {
+  authorization: {
+    requiredScopes: ['org_apps:read'],
+    allowedRoles: ['org_admin', 'org_member'],
+  },
+  // input, output, and fulfilment...
+});
+```
+
+Every required scope must be present and at least one allowed role must match. When both lists are declared,
+both conditions apply. A restricted tool is omitted from `tools/list` for an ineligible customer and a
+direct `tools/call` still fails closed. Do not use unverified page context, request arguments, connector
+responses, or an arbitrary generic `roles` claim as authorization input.
+
 Tool code calls the connector normally:
 
 ```ts

package/skills/claude-code/examples/customer-auth/src/server.ts

@@ -80,6 +80,7 @@ export default server(
         tenant: 'firebase.tenant',
         orgs: 'claims.orgs',
         roles: 'claims.roles',
+        scopes: 'claims.scopes',
       },
     }),
     instructions:
@@ -117,6 +118,10 @@ export default server(
     tool('list_org_apps', {
       title: 'List organization apps',
       description: 'List NoodleSeed.com apps for an organization from the dev app API.',
+      authorization: {
+        requiredScopes: ['org_apps:read'],
+        allowedRoles: ['org_admin', 'org_member'],
+      },
       input: z.object({
         org_id: z.string().meta({ title: 'Organization' }),
         skip: z.number().int().min(0).optional().meta({ title: 'Starting item' }),

package/skills/claude-code/examples/customer-auth/test/server.test.ts

@@ -24,9 +24,22 @@ describe('customer-auth example', () => {
       colorScheme: 'auto',
     });
     expect(manifest.server.auth).toMatchObject({
+      kind: 'bridge',
+      provider: 'firebase',
       projectId: '${env.FIREBASE_PROJECT_ID}',
       apiKey: '${env.FIREBASE_WEB_API_KEY}',
       authDomain: '${env.FIREBASE_AUTH_DOMAIN}',
+      user: {
+        roles: 'claims.roles',
+        scopes: 'claims.scopes',
+      },
+    });
+    expect(manifest.tools.find((tool) => tool.name === 'list_org_apps')?.authorization).toEqual({
+      requiredScopes: ['org_apps:read'],
+      allowedRoles: ['org_admin', 'org_member'],
     });
+    expect(
+      manifest.tools.find((tool) => tool.name === 'list_my_organizations')?.authorization,
+    ).toBeUndefined();
   });
 });

package/skills/claude-code/executing-noodle-plans/SKILL.md

@@ -3,7 +3,7 @@ name: executing-noodle-plans
 description: "Use when the user asks to execute an approved, decision-complete implementation plan for a Noodle Seed project task by task with test-first changes, review, recovery, and final verification."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:6a9f132ddb79352e -->
+<!-- noodle-skill version:0.50.0 hash:6a9f132ddb79352e -->
 
 # Execute a Noodle Seed implementation plan
 

package/skills/claude-code/publishing-mcp-integrations/SKILL.md

@@ -3,7 +3,7 @@ name: publishing-mcp-integrations
 description: "Use when preparing, reviewing, or submitting a Noodle Seed MCP integration to a host or app directory."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:efffbf82007f935d -->
+<!-- noodle-skill version:0.50.0 hash:efffbf82007f935d -->
 
 # publishing-mcp-integrations
 

package/skills/claude-code/references/authoring-workflow.md

@@ -8,6 +8,7 @@
 - Connectors
 - HTTP connector example (full server)
 - Customer OAuth for remote MCP clients
+- Per-tool authorization
 - Delegated downstream auth (call your API as the signed-in user)
 - Invocation context
 - Compute connector example
@@ -108,6 +109,28 @@ For `customerAuth.oidc(...)` and `.federatedOidc(...)`, the application develope
 
 That metadata must expose HTTPS `authorization_endpoint`, `token_endpoint`, `jwks_uri`, and RFC 7591 `registration_endpoint`; advertise authorization-code and refresh-token grants, Dynamic Client Registration, PKCE with `code_challenge_methods_supported: ["S256"]`, and public clients with `token_endpoint_auth_methods_supported: ["none"]`. Implement RFC 8707 `resource`, mint access-token `aud` for the exact MCP resource URL, and publish only public signing keys in JWKS. Run `noodle auth doctor src/server.ts`; its issuer-readiness probes perform bounded read-only GET checks and never register a client. A successful `noodle deploy --access customers` reports the same readiness without turning a diagnostic failure into a failed deployment.
 
+## Per-tool authorization
+
+Keep endpoint authentication in `customerAuth.*(...)`, then narrow individual tools with the optional typed `authorization` rule. Every `requiredScopes` value is required; any one `allowedRoles` value is sufficient; when both lists are present, both conditions apply. Omit `authorization` for an unrestricted tool. Do not invent a policy expression language or infer authorization from tool arguments, page context, connector output, email domains, or other unverified data.
+
+```ts
+auth: customerAuth.oidc({
+  issuer: 'https://id.example.com',
+  audience: 'https://api.example.com/mcp',
+  claims: { roles: 'permissions.roles', scopes: 'permissions.scopes' },
+}),
+
+tool('list_org_apps', {
+  authorization: {
+    requiredScopes: ['org_apps:read'],
+    allowedRoles: ['org_admin', 'org_member'],
+  },
+  // input, output, and fulfilment...
+})
+```
+
+Role values are trusted only from the explicitly configured claim path (or the platform-private bridge role claim). Direct OIDC scopes default to standard `scope`, `scp`, or `scopes` claims unless `claims.scopes` is configured. Embedded-assistant backends pass verified `user.roles` and `user.scopes` separately during `createAssistantSession(...)`; page context never grants either. Claim values must be a string or string array; malformed or oversized values fail closed. Eligible tools remain in authored order in `tools/list`; ineligible tools are omitted and a guessed direct call is still denied before argument validation or connector execution. Scope denials use MCP OAuth step-up metadata without disclosing role names.
+
 ## Delegated downstream auth (call your API as the signed-in user)
 
 Use delegated connector auth when the downstream API must enforce its own per-user authorization — a shared service credential plus a forwarded user id would bypass it. Three shapes exist; pick by who owns the downstream:

package/skills/claude-code/references/embedded-assistant.md

@@ -110,7 +110,9 @@ Do not put these model values in the embedding SaaS environment. A production de
 
 ## Access modes and customer auth
 
-Session exchange authenticates with the backend client credentials, so the embed works under any `--access` mode. Add `--access customers` only when verified end customers should also call the MCP endpoint directly. That mode requires `server.auth`; `noodle deploy` preflights the rule locally and fails with `server_auth_required` before contacting the service. Fix by adding auth to server options:
+Session exchange authenticates with the backend client credentials, so the embed works under any `--access` mode. The assistant does not select direct MCP access or protected-resource discovery. If protected-resource metadata advertises an unexpected issuer, inspect the exact active deployment before changing auth by following `references/troubleshooting.md`.
+
+Add `--access customers` only when verified end customers should also call the MCP endpoint directly. That mode requires `server.auth`; `noodle deploy` preflights the rule locally and fails with `server_auth_required` before contacting the service. Fix by adding auth to server options:
 
 ```ts
 auth: customerAuth.federatedOidc({
@@ -154,7 +156,12 @@ export async function POST(request: Request) {
     clientId: process.env.NOODLE_ASSISTANT_CLIENT_ID!,
     clientSecret: process.env.NOODLE_ASSISTANT_CLIENT_SECRET!,
     origin: process.env.PUBLIC_APP_ORIGIN!,
-    user: { id: user.id, email: user.email, roles: user.roles },
+    user: {
+      id: user.id,
+      email: user.email,
+      roles: user.roles,
+      scopes: user.scopes,
+    },
     context,
     // Saved, backend-verified user preferences outrank browser hints.
     preferences: { locale: user.locale, timeZone: user.timeZone },
@@ -163,7 +170,7 @@ export async function POST(request: Request) {
 }
 ```
 
-Authenticate before exchange. Source `origin` from trusted server configuration or strictly match the request origin against the same exact allowlist; never accept an arbitrary request header. Treat page context as untrusted model context, never authorization. Forward the helper response unchanged.
+Authenticate before exchange. Pass backend-verified `user.roles` and OAuth-style `user.scopes` separately; they govern the same per-tool authorization rules as verified MCP bearer claims. Source `origin` from trusted server configuration or strictly match the request origin against the same exact allowlist; never accept an arbitrary request header. Treat page context as untrusted model context, never authorization. Forward the helper response unchanged.
 
 `serviceUrl` is the Noodle Seed control-plane base URL: the value `noodle assistant clients create` prints, also stored as `serviceUrl` in `deployment.json`. It is NOT the deployment MCP endpoint (`url`, which ends in `/v1/mcp` and rejects session exchange). Never probe or guess endpoints with real credentials.
 
@@ -204,7 +211,13 @@ The embedding developer defines what authenticated session context the assistant
 ```ts
 const session = await createAssistantSession({
   serviceUrl, clientId, clientSecret, origin,
-  user: { id: user.id, email: user.email, name: user.name },
+  user: {
+    id: user.id,
+    email: user.email,
+    name: user.name,
+    roles: user.roles,
+    scopes: user.scopes,
+  },
   claims: { displayName: user.name, accountTier: account.tier, region: account.region },
 });
 ```

package/skills/claude-code/references/troubleshooting.md

@@ -3,6 +3,7 @@
 ## Contents
 
 - First moves
+- Customer-auth metadata
 - Symptom map
 
 ## First moves
@@ -11,6 +12,12 @@ Re-run the local gates before debugging in-host: `noodle validate`, `noodle chec
 
 For protocol/conformance checks, the headless harness is `@mcpjam/cli`, not a `noodle` subcommand. Use it against a local `noodle dev` URL without an access token, or against hosted URLs through the host/OAuth flow printed by `noodle connect`.
 
+## Customer-auth metadata
+
+Adding `embeddedAssistant(...)` does not select the MCP access mode or authorization server. Before changing auth, inspect the exact active deployment with `noodle deployments list --org <org> --app <app> --env <env> --json` and match its active deployment ID, server version, and access mode to the endpoint being tested.
+
+For `customers` access, Direct or federated customer auth must advertise the configured tenant issuer; a managed Noodle bridge must advertise the Noodle authorization server. Owner-only access advertises the platform authorization server. If a direct or federated `customers` deployment still advertises the platform issuer, treat it as `customer_auth_state_inconsistent` and escalate with the endpoint, active deployment ID, and sanitized protected-resource metadata. Do not proxy, rewrite, rotate, or redeploy to hide the mismatch. Never share bearer tokens, refresh tokens, client secrets, or credential files.
+
 ## Symptom map
 
 | Symptom | Likely cause | Fix |

package/skills/claude-code/reporting-noodle-feedback/SKILL.md

@@ -3,7 +3,7 @@ name: reporting-noodle-feedback
 description: "Use when a Noodle Seed bug, misleading instruction, missing capability, or concrete product improvement should be proposed to the user."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:0f404109f4845683 -->
+<!-- noodle-skill version:0.50.0 hash:0f404109f4845683 -->
 
 # reporting-noodle-feedback
 

package/skills/claude-code/verifying-mcp-delivery/SKILL.md

@@ -3,7 +3,7 @@ name: verifying-mcp-delivery
 description: "Use when proving a Noodle Seed MCP project works at a named compile, local, connector, App, host, deployment, or production evidence level."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:6ef6ef551e26b78e -->
+<!-- noodle-skill version:0.50.0 hash:6ef6ef551e26b78e -->
 
 # verifying-mcp-delivery
 

package/skills/codex/SKILL.md

@@ -3,7 +3,7 @@ name: noodle-seed
 description: "Use when building, validating, testing, deploying, or operating a local or hosted Noodle Seed MCP server or app authored in TypeScript with the noodle CLI."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:cd6ca0d915e6acb9 -->
+<!-- noodle-skill version:0.50.0 hash:cd6ca0d915e6acb9 -->
 
 # Noodle Seed
 

package/skills/codex/authoring-mcp-servers/SKILL.md

@@ -3,7 +3,7 @@ name: authoring-mcp-servers
 description: "Use when creating or extending a headless Noodle Seed MCP server, tool, resource, prompt, or typed model-facing capability."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:0b2fd8c7e43fc69f -->
+<!-- noodle-skill version:0.50.0 hash:0b2fd8c7e43fc69f -->
 
 # authoring-mcp-servers
 

package/skills/codex/building-mcp-apps/SKILL.md

@@ -3,7 +3,7 @@ name: building-mcp-apps
 description: "Use when a Noodle Seed MCP App, widget, interactive card, visual interaction, or host-visible UI is the primary requested outcome."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:f7fa54992c8d7692 -->
+<!-- noodle-skill version:0.50.0 hash:f7fa54992c8d7692 -->
 
 # building-mcp-apps
 

package/skills/codex/connecting-apis-to-mcp/SKILL.md

@@ -3,7 +3,7 @@ name: connecting-apis-to-mcp
 description: "Use when credentials, an API URL, an OpenAPI document, or an observed response must become real Noodle Seed MCP behavior."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:1e86b8704f407bd3 -->
+<!-- noodle-skill version:0.50.0 hash:1e86b8704f407bd3 -->
 
 # connecting-apis-to-mcp
 

package/skills/codex/debugging-mcp-delivery/SKILL.md

@@ -3,7 +3,7 @@ name: debugging-mcp-delivery
 description: "Use when an existing Noodle Seed MCP project has a concrete validation, runtime, connector, App, host, deployment, or production failure."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:aa715bae12041d7c -->
+<!-- noodle-skill version:0.50.0 hash:aa715bae12041d7c -->
 
 # debugging-mcp-delivery
 

package/skills/codex/deploying-mcp-services/SKILL.md

@@ -3,7 +3,7 @@ name: deploying-mcp-services
 description: "Use when the user explicitly requests a Noodle Seed hosted link, configuration write, deployment, access change, rollback, or connection write."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:93e735b7ffb45df1 -->
+<!-- noodle-skill version:0.50.0 hash:93e735b7ffb45df1 -->
 
 # deploying-mcp-services
 

package/skills/codex/designing-mcp-products/SKILL.md

@@ -3,7 +3,7 @@ name: designing-mcp-products
 description: "Use when a Noodle Seed MCP product idea needs conversational fit, user benefit, scope, interaction, or evidence design before implementation."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:76cce86729cffbee -->
+<!-- noodle-skill version:0.50.0 hash:76cce86729cffbee -->
 
 # designing-mcp-products
 

package/skills/codex/embedding-mcp-assistants/SKILL.md

@@ -3,7 +3,7 @@ name: embedding-mcp-assistants
 description: "Use when embedding a Noodle assistant into an existing SaaS or web application with browser, identity, session, and credential boundaries."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:cc54a67f21c0ecdb -->
+<!-- noodle-skill version:0.50.0 hash:cc54a67f21c0ecdb -->
 
 # embedding-mcp-assistants
 

package/skills/codex/examples/customer-auth/README.md

@@ -15,7 +15,9 @@ surface for org discovery:
 
 - `list_my_organizations` lists the NoodleSeed.com organizations the signed-in customer belongs to (no
   arguments — the org set comes from the verified customer session).
-- `list_org_apps` lists apps for one of those organizations through the dev app API.
+- `list_org_apps` lists apps for one of those organizations through the dev app API. It is visible and
+  callable only when the verified customer has the `org_apps:read` scope and either the `org_admin` or
+  `org_member` role.
 
 The two tools chain: `list_my_organizations` surfaces the `org_id`s the customer can act on, and
 `list_org_apps` takes one of those `org_id`s. There is no NoodleSeed-specific SDK helper. The downstream API
@@ -34,6 +36,19 @@ bounded read-only GET checks and never register a client. A successful
 `noodle deploy --access customers` reports the same findings as nonblocking warnings; the application team
 repairs the issuer rather than adding a Noodle OAuth proxy.
 
+Adding the embedded assistant does not choose or rewrite MCP customer auth. Inspect the exact active
+deployment before changing configuration:
+
+```sh
+noodle deployments list --org <org> --app <app> --env <env> --json
+```
+
+This Firebase bridge intentionally advertises the Noodle authorization server. A direct or federated
+replacement must advertise its configured tenant issuer. If the exact active direct/federated `customers`
+deployment instead advertises the platform issuer, report `customer_auth_state_inconsistent` with only the
+endpoint, deployment ID, server version, and sanitized protected-resource metadata. Do not share tokens or
+secrets, proxy or rewrite metadata, rotate credentials, or redeploy repeatedly to conceal the mismatch.
+
 During MCP OAuth login, Noodle Cloud hosts the Firebase bridge page at
 `https://cloud.noodleseed.dev/oauth/customer/firebase/authorize`. The customer app does not add an
 authorization route. The SaaS operator only configures Firebase Auth to allow the Noodle Cloud origin, and
@@ -61,9 +76,10 @@ auth: customerAuth.firebase({
     email: 'email',
     name: 'name',
     tenant: 'firebase.tenant',
-    orgs: 'claims.orgs',
-    roles: 'claims.roles',
-  },
+        orgs: 'claims.orgs',
+        roles: 'claims.roles',
+        scopes: 'claims.scopes',
+      },
 }),
 ```
 
@@ -79,6 +95,24 @@ auth: {
 },
 ```
 
+The mapped `roles` and `scopes` paths are read only after Firebase verifies the ID token. The restricted
+tool declares its rule beside the rest of its public contract:
+
+```ts
+tool('list_org_apps', {
+  authorization: {
+    requiredScopes: ['org_apps:read'],
+    allowedRoles: ['org_admin', 'org_member'],
+  },
+  // input, output, and fulfilment...
+});
+```
+
+Every required scope must be present and at least one allowed role must match. When both lists are declared,
+both conditions apply. A restricted tool is omitted from `tools/list` for an ineligible customer and a
+direct `tools/call` still fails closed. Do not use unverified page context, request arguments, connector
+responses, or an arbitrary generic `roles` claim as authorization input.
+
 Tool code calls the connector normally:
 
 ```ts

package/skills/codex/examples/customer-auth/src/server.ts

@@ -80,6 +80,7 @@ export default server(
         tenant: 'firebase.tenant',
         orgs: 'claims.orgs',
         roles: 'claims.roles',
+        scopes: 'claims.scopes',
       },
     }),
     instructions:
@@ -117,6 +118,10 @@ export default server(
     tool('list_org_apps', {
       title: 'List organization apps',
       description: 'List NoodleSeed.com apps for an organization from the dev app API.',
+      authorization: {
+        requiredScopes: ['org_apps:read'],
+        allowedRoles: ['org_admin', 'org_member'],
+      },
       input: z.object({
         org_id: z.string().meta({ title: 'Organization' }),
         skip: z.number().int().min(0).optional().meta({ title: 'Starting item' }),

package/skills/codex/examples/customer-auth/test/server.test.ts

@@ -24,9 +24,22 @@ describe('customer-auth example', () => {
       colorScheme: 'auto',
     });
     expect(manifest.server.auth).toMatchObject({
+      kind: 'bridge',
+      provider: 'firebase',
       projectId: '${env.FIREBASE_PROJECT_ID}',
       apiKey: '${env.FIREBASE_WEB_API_KEY}',
       authDomain: '${env.FIREBASE_AUTH_DOMAIN}',
+      user: {
+        roles: 'claims.roles',
+        scopes: 'claims.scopes',
+      },
+    });
+    expect(manifest.tools.find((tool) => tool.name === 'list_org_apps')?.authorization).toEqual({
+      requiredScopes: ['org_apps:read'],
+      allowedRoles: ['org_admin', 'org_member'],
     });
+    expect(
+      manifest.tools.find((tool) => tool.name === 'list_my_organizations')?.authorization,
+    ).toBeUndefined();
   });
 });

package/skills/codex/executing-noodle-plans/SKILL.md

@@ -3,7 +3,7 @@ name: executing-noodle-plans
 description: "Use when the user asks to execute an approved, decision-complete implementation plan for a Noodle Seed project task by task with test-first changes, review, recovery, and final verification."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:6a9f132ddb79352e -->
+<!-- noodle-skill version:0.50.0 hash:6a9f132ddb79352e -->
 
 # Execute a Noodle Seed implementation plan
 

package/skills/codex/publishing-mcp-integrations/SKILL.md

@@ -3,7 +3,7 @@ name: publishing-mcp-integrations
 description: "Use when preparing, reviewing, or submitting a Noodle Seed MCP integration to a host or app directory."
 ---
 
-<!-- noodle-skill version:0.48.2 hash:efffbf82007f935d -->
+<!-- noodle-skill version:0.50.0 hash:efffbf82007f935d -->
 
 # publishing-mcp-integrations
 

package/skills/codex/references/authoring-workflow.md

@@ -8,6 +8,7 @@
 - Connectors
 - HTTP connector example (full server)
 - Customer OAuth for remote MCP clients
+- Per-tool authorization
 - Delegated downstream auth (call your API as the signed-in user)
 - Invocation context
 - Compute connector example
@@ -108,6 +109,28 @@ For `customerAuth.oidc(...)` and `.federatedOidc(...)`, the application develope
 
 That metadata must expose HTTPS `authorization_endpoint`, `token_endpoint`, `jwks_uri`, and RFC 7591 `registration_endpoint`; advertise authorization-code and refresh-token grants, Dynamic Client Registration, PKCE with `code_challenge_methods_supported: ["S256"]`, and public clients with `token_endpoint_auth_methods_supported: ["none"]`. Implement RFC 8707 `resource`, mint access-token `aud` for the exact MCP resource URL, and publish only public signing keys in JWKS. Run `noodle auth doctor src/server.ts`; its issuer-readiness probes perform bounded read-only GET checks and never register a client. A successful `noodle deploy --access customers` reports the same readiness without turning a diagnostic failure into a failed deployment.
 
+## Per-tool authorization
+
+Keep endpoint authentication in `customerAuth.*(...)`, then narrow individual tools with the optional typed `authorization` rule. Every `requiredScopes` value is required; any one `allowedRoles` value is sufficient; when both lists are present, both conditions apply. Omit `authorization` for an unrestricted tool. Do not invent a policy expression language or infer authorization from tool arguments, page context, connector output, email domains, or other unverified data.
+
+```ts
+auth: customerAuth.oidc({
+  issuer: 'https://id.example.com',
+  audience: 'https://api.example.com/mcp',
+  claims: { roles: 'permissions.roles', scopes: 'permissions.scopes' },
+}),
+
+tool('list_org_apps', {
+  authorization: {
+    requiredScopes: ['org_apps:read'],
+    allowedRoles: ['org_admin', 'org_member'],
+  },
+  // input, output, and fulfilment...
+})
+```
+
+Role values are trusted only from the explicitly configured claim path (or the platform-private bridge role claim). Direct OIDC scopes default to standard `scope`, `scp`, or `scopes` claims unless `claims.scopes` is configured. Embedded-assistant backends pass verified `user.roles` and `user.scopes` separately during `createAssistantSession(...)`; page context never grants either. Claim values must be a string or string array; malformed or oversized values fail closed. Eligible tools remain in authored order in `tools/list`; ineligible tools are omitted and a guessed direct call is still denied before argument validation or connector execution. Scope denials use MCP OAuth step-up metadata without disclosing role names.
+
 ## Delegated downstream auth (call your API as the signed-in user)
 
 Use delegated connector auth when the downstream API must enforce its own per-user authorization — a shared service credential plus a forwarded user id would bypass it. Three shapes exist; pick by who owns the downstream: