@zackbart/connecta 0.24.1 → 0.24.2

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to this package are documented here.
 
+## 0.24.2 — 2026-09-16
+
+`connectorAccess` can now grant individual tools, and a deployment can declare
+named pools served at `/mcp/<pool>`. Nothing changes for a deployment that
+returns `"all"` or connector ids and declares no pools.
+
+### Added
+
+- **Named tool pools at `/mcp/<pool>`.** `ConnectaConfig.pools` declares a
+  slice of connector ids and exact `connector.tool` addresses plus a `grant`
+  predicate over the authenticated identity, denied by default. The endpoint
+  serves the pool intersected with the identity's `connectorAccess`, so it can
+  only narrow. An undeclared name, a refusing grant, and a throwing grant are
+  one identical 404. Misdeclared pools refuse to boot. Clerk's 401 challenge
+  and protected-resource metadata follow the pool path so OAuth discovery
+  matches the URL the client used. Ethos records the decision.
+
+- **Tool-level grants in `identity.connectorAccess`.** Entries may be a
+  connector id (every tool) or an exact `connector.tool` address (that tool
+  only); grants are additive. The scoped registry view filters below the
+  catalog service, so `search_tools`, `describe_tools`, `call_tool`,
+  `call_destructive_tool`, a program's `connecta.search` and `connecta.call`,
+  and the connection UI all see the same list, and an ungranted tool fails as
+  `unknown_tool` exactly like an absent one. There is no wildcard: a remote
+  catalog that drifts cannot widen a grant. An address the catalog lacks is
+  unreachable and warned once per isolate. An unparseable entry refuses the
+  request with 403 rather than failing open.
+
 ## 0.24.1 — 2026-09-08
 
 ### Added

package/dist/auth/clerk.d.ts

@@ -27,10 +27,5 @@ export interface ClerkAuthOptions {
     /** Optional hosted Account Portal sign-up URL for operator pages. Absolute https only. */
     signUpUrl?: string;
 }
-/**
- * Clerk inbound auth.
- *
- * `allowedDomains` and `gate` decide who is admitted; both must pass.
- */
 export declare function clerkAuth(opts: ClerkAuthOptions): InboundAuth;
 export {};

package/dist/auth/clerk.js

@@ -207,6 +207,11 @@ function emailDomain(email) {
  *
  * `allowedDomains` and `gate` decide who is admitted; both must pass.
  */
+/** `"/<pool>"` for a pool endpoint path, null for `/mcp` and anything else. */
+function mcpPoolSuffix(pathname) {
+    const match = /^\/mcp(\/[a-z0-9_-]+)$/.exec(pathname);
+    return match ? match[1] : null;
+}
 export function clerkAuth(opts) {
     assertNoRetiredToolkitOptions("clerkAuth", opts);
     // Before the Clerk client, so a malformed key fails as a connecta
@@ -284,9 +289,13 @@ export function clerkAuth(opts) {
         pendingActivityLabels.set(userId, lookup);
         return lookup;
     };
-    const unauthorized = (baseUrl, tokenPresent) => {
+    const unauthorized = (baseUrl, tokenPresent, request) => {
         const error = tokenPresent ? `error="invalid_token", ` : "";
-        const meta = `${resolveBase(baseUrl)}/.well-known/oauth-protected-resource`;
+        // A pool endpoint is its own protected resource: the challenge names the
+        // metadata document whose `resource` matches the URL the client used, or
+        // RFC 9728 tells it to reject the mismatch.
+        const pool = mcpPoolSuffix(new URL(request.url).pathname);
+        const meta = `${resolveBase(baseUrl)}/.well-known/oauth-protected-resource${pool ? `/mcp${pool}` : ""}`;
         return new Response(JSON.stringify({ error: "unauthorized" }), {
             status: 401,
             headers: {
@@ -384,10 +393,14 @@ export function clerkAuth(opts) {
                 return new Response(null, { status: 204, headers: CORS_HEADERS });
             }
             const base = resolveBase(baseUrl);
+            const pool = pathname.startsWith("/.well-known/oauth-protected-resource/mcp/")
+                ? mcpPoolSuffix(pathname.slice("/.well-known/oauth-protected-resource".length))
+                : null;
             if (pathname === "/.well-known/oauth-protected-resource" ||
-                pathname === "/.well-known/oauth-protected-resource/mcp") {
+                pathname === "/.well-known/oauth-protected-resource/mcp" ||
+                pool) {
                 return Response.json({
-                    resource: `${base}/mcp`,
+                    resource: `${base}/mcp${pool ?? ""}`,
                     authorization_servers: [frontendApiUrl],
                     bearer_methods_supported: ["header"],
                     scopes_supported: scopes,
@@ -430,7 +443,7 @@ export function clerkAuth(opts) {
                         ` tokenShape=${tokenShape(request)}`);
                     return {
                         ok: false,
-                        response: unauthorized(baseUrl, tokenPresent),
+                        response: unauthorized(baseUrl, tokenPresent, request),
                     };
                 }
                 // Session JWTs carry `azp` (the origin they were minted for); pin it
@@ -444,7 +457,7 @@ export function clerkAuth(opts) {
                         console.warn(`[connecta] session token azp mismatch: azp=${azp} expected=${origin}`);
                         return {
                             ok: false,
-                            response: unauthorized(baseUrl, tokenPresent),
+                            response: unauthorized(baseUrl, tokenPresent, request),
                         };
                     }
                 }
@@ -452,10 +465,10 @@ export function clerkAuth(opts) {
             }
             catch (error) {
                 console.warn(`[connecta] clerk authenticateRequest threw: ${error instanceof Error ? error.message : String(error)} tokenShape=${tokenShape(request)}`);
-                return { ok: false, response: unauthorized(baseUrl, true) };
+                return { ok: false, response: unauthorized(baseUrl, true, request) };
             }
             if (!userId) {
-                return { ok: false, response: unauthorized(baseUrl, true) };
+                return { ok: false, response: unauthorized(baseUrl, true, request) };
             }
             if (!(await checkGate(userId))) {
                 return { ok: false, response: forbidden() };

package/dist/connector-access.d.ts

@@ -0,0 +1,32 @@
+import type { ToolAccess } from "./registry.js";
+import type { AuthenticatedIdentity } from "./types.js";
+/** A declared pool after construction-time validation. */
+export interface ResolvedPool {
+    access: ConnectorAccess;
+    grant(identity: Readonly<AuthenticatedIdentity>): boolean | Promise<boolean>;
+}
+export declare const POOL_NAME_RE: RegExp;
+/**
+ * One derived view: which connectors, and for connectors granted by address
+ * only, which tools. A connector absent from `toolAccess` is visible whole.
+ */
+export interface ConnectorAccess {
+    connectorIds: "all" | readonly string[];
+    toolAccess?: ToolAccess;
+}
+/**
+ * Normalize a grant list. A bare connector id grants every tool on that
+ * connector; a `connector.tool` address grants one tool. Grants are additive,
+ * so a bare id beside addresses for the same connector means the whole
+ * connector. Anything else — an unknown shape, an empty tool name, a
+ * non-string — throws, and the caller decides whether that is a construction
+ * failure or a 403: a grant that cannot be parsed must never fail open.
+ */
+export declare function parseConnectorAccess(value: unknown): ConnectorAccess;
+/**
+ * The view a pool endpoint serves: the pool's grants, never wider than the
+ * identity's own. A connector or tool outside either side is gone; a
+ * connector whose tool intersection is empty is gone too, so the pool can
+ * only narrow what the identity resolver already allowed.
+ */
+export declare function intersectAccess(ceiling: ConnectorAccess, pool: ConnectorAccess): ConnectorAccess;

package/dist/connector-access.js

@@ -0,0 +1,79 @@
+export const POOL_NAME_RE = /^[a-z0-9_-]+$/;
+const CONNECTOR_ID_RE = /^[a-z0-9_-]+$/;
+// MCP does not restrict tool names, and remote servers ship spaced and
+// non-ASCII ones. Only control characters are refused, so a grant for a
+// legitimately named tool cannot 403 the whole identity at request time.
+const TOOL_ADDRESS_RE = /^[a-z0-9_-]+\..{1,256}$/su;
+const hasControlCharacter = (value) => [...value].some((ch) => {
+    const code = ch.codePointAt(0);
+    return code < 0x20 || code === 0x7f;
+});
+/**
+ * Normalize a grant list. A bare connector id grants every tool on that
+ * connector; a `connector.tool` address grants one tool. Grants are additive,
+ * so a bare id beside addresses for the same connector means the whole
+ * connector. Anything else — an unknown shape, an empty tool name, a
+ * non-string — throws, and the caller decides whether that is a construction
+ * failure or a 403: a grant that cannot be parsed must never fail open.
+ */
+export function parseConnectorAccess(value) {
+    if (value === "all")
+        return { connectorIds: "all" };
+    if (!Array.isArray(value))
+        throw new Error("invalid connector permission");
+    const whole = new Set();
+    const partial = new Map();
+    for (const entry of value) {
+        if (typeof entry !== "string")
+            throw new Error("invalid connector permission");
+        if (CONNECTOR_ID_RE.test(entry)) {
+            whole.add(entry);
+            continue;
+        }
+        if (!TOOL_ADDRESS_RE.test(entry) || hasControlCharacter(entry))
+            throw new Error("invalid connector permission");
+        const dot = entry.indexOf(".");
+        const connectorId = entry.slice(0, dot);
+        const tools = partial.get(connectorId) ?? new Set();
+        tools.add(entry.slice(dot + 1));
+        partial.set(connectorId, tools);
+    }
+    for (const id of whole)
+        partial.delete(id);
+    const connectorIds = [...new Set([...whole, ...partial.keys()])];
+    return partial.size > 0
+        ? { connectorIds, toolAccess: partial }
+        : { connectorIds };
+}
+/**
+ * The view a pool endpoint serves: the pool's grants, never wider than the
+ * identity's own. A connector or tool outside either side is gone; a
+ * connector whose tool intersection is empty is gone too, so the pool can
+ * only narrow what the identity resolver already allowed.
+ */
+export function intersectAccess(ceiling, pool) {
+    if (pool.connectorIds === "all")
+        return ceiling;
+    const allowedIds = ceiling.connectorIds === "all"
+        ? null
+        : new Set(ceiling.connectorIds);
+    const connectorIds = [];
+    const toolAccess = new Map();
+    for (const id of pool.connectorIds) {
+        if (allowedIds && !allowedIds.has(id))
+            continue;
+        const fromPool = pool.toolAccess?.get(id);
+        const fromCeiling = ceiling.toolAccess?.get(id);
+        if (fromPool && fromCeiling) {
+            const both = new Set([...fromPool].filter((name) => fromCeiling.has(name)));
+            if (both.size === 0)
+                continue;
+            toolAccess.set(id, both);
+        }
+        else if (fromPool ?? fromCeiling) {
+            toolAccess.set(id, (fromPool ?? fromCeiling));
+        }
+        connectorIds.push(id);
+    }
+    return toolAccess.size > 0 ? { connectorIds, toolAccess } : { connectorIds };
+}

package/dist/index.d.ts

@@ -105,7 +105,12 @@ export interface ConnectaAdmissionConfig {
 /** Config-owned identity rules for one deployment and tenant. */
 export type ConnectorPermission = "all" | "none" | readonly string[];
 export interface ConnectaIdentityConfig {
-    /** Connector ids this admitted identity may discover and call. */
+    /**
+     * What this admitted identity may discover and call: `"all"`, or a list
+     * whose entries are connector ids (the whole connector) and `connector.tool`
+     * addresses (that tool only). Grants are additive. An address naming a tool
+     * the catalog lacks is unreachable and warned once, never widened.
+     */
     connectorAccess?(identity: Readonly<AuthenticatedIdentity>): "all" | readonly string[] | Promise<"all" | readonly string[]>;
     /** Global payload-free activity reads. Defaults to interactive humans. */
     activityAccess?(principal: Readonly<IdentityReference>): boolean | Promise<boolean>;
@@ -114,12 +119,29 @@ export interface ConnectaIdentityConfig {
     /** Connecting or changing the caller's personal account. Defaults to none. */
     personalConnection?(identity: Readonly<AuthenticatedIdentity>): ConnectorPermission | Promise<ConnectorPermission>;
 }
+/**
+ * A named tool pool served at `/mcp/<name>`. The pool is the slice a client
+ * pointed at that endpoint may see; the identity's own `connectorAccess`
+ * remains its ceiling and the pool can only narrow it.
+ */
+export interface ConnectaPoolConfig {
+    /** Connector ids and exact `connector.tool` addresses in this pool. */
+    tools: readonly string[];
+    /**
+     * Whether this admitted identity may open the pool. Denied by default:
+     * a pool with no grant serves nobody. A false return, a throw, and an
+     * undeclared pool name are the same 404.
+     */
+    grant?(identity: Readonly<AuthenticatedIdentity>): boolean | Promise<boolean>;
+}
 export interface ConnectaConfig {
     connectors: Connector[];
     /** Inbound auth adapters. Includes bearerToken(...); omit for open (dev). */
     auth?: InboundAuth | InboundAuth[];
     /** Code-derived connection visibility and independent management permissions. */
     identity?: ConnectaIdentityConfig;
+    /** Named tool pools, each served at `/mcp/<name>` to identities its grant admits. */
+    pools?: Record<string, ConnectaPoolConfig>;
     /** KVStorage impl. Defaults to memoryStorage(). */
     storage?: KVStorage;
     /**

package/dist/index.js

@@ -1,5 +1,6 @@
 import { credentialTestRule, describeCredentialTestMismatch, } from "./credential-rules.js";
 import { Registry } from "./registry.js";
+import { parseConnectorAccess, POOL_NAME_RE } from "./connector-access.js";
 import { createFetchHandler } from "./server.js";
 import { droppedBrandingUrls, droppedUiAuthUrls } from "./branding.js";
 import { memoryStorage } from "./storage/memory.js";
@@ -56,6 +57,7 @@ const CONFIG_SCHEMA = {
         credentialAdministration: null,
         personalConnection: null,
     },
+    pools: null,
     storage: null,
     publicUrl: null,
     activity: null,
@@ -145,6 +147,67 @@ function assertKnownConfig(config) {
         throw new Error("ConnectaConfig.activity must be created with activityHistory(...)");
     }
 }
+/**
+ * Validate declared pools against the connector set. Everything checkable at
+ * construction throws here: a malformed name, an unparseable grant, an
+ * unknown connector id, a tool address on an `api()` connector whose static
+ * catalog lacks it. Remote catalogs load lazily, so their addresses are
+ * checked at catalog load instead and stay unreachable until they match.
+ */
+function resolvePools(pools, registry) {
+    const resolved = new Map();
+    if (!pools)
+        return resolved;
+    if (typeof pools !== "object" || Array.isArray(pools)) {
+        throw new Error("ConnectaConfig.pools must be an object keyed by pool name");
+    }
+    for (const [name, pool] of Object.entries(pools)) {
+        if (!POOL_NAME_RE.test(name)) {
+            throw new Error(`ConnectaConfig.pools: pool name "${name}" must match [a-z0-9_-]+`);
+        }
+        if (!pool || typeof pool !== "object" || !Array.isArray(pool.tools)) {
+            throw new Error(`ConnectaConfig.pools.${name}: tools must be an array of connector ids or connector.tool addresses`);
+        }
+        if (pool.grant !== undefined && typeof pool.grant !== "function") {
+            throw new Error(`ConnectaConfig.pools.${name}: grant must be a function`);
+        }
+        // A misspelled `grant` would otherwise boot as a deny-all pool with only a
+        // per-request log line to say so; that is fail-closed, but the rule here
+        // is that structural mistakes refuse to boot.
+        for (const key of Object.keys(pool)) {
+            if (key !== "tools" && key !== "grant") {
+                throw new Error(`ConnectaConfig.pools.${name}: unknown option "${key}"`);
+            }
+        }
+        let access;
+        try {
+            access = parseConnectorAccess(pool.tools);
+        }
+        catch {
+            throw new Error(`ConnectaConfig.pools.${name}: tools must be connector ids or connector.tool addresses`);
+        }
+        if (access.connectorIds === "all" || access.connectorIds.length === 0) {
+            throw new Error(`ConnectaConfig.pools.${name}: a pool must name at least one connector or tool`);
+        }
+        for (const id of access.connectorIds) {
+            const connector = registry.getConnector(id);
+            if (!connector) {
+                throw new Error(`ConnectaConfig.pools.${name}: unknown connector "${id}"`);
+            }
+            const granted = access.toolAccess?.get(id);
+            if (!granted || !connector.staticTools)
+                continue;
+            const known = new Set(connector.staticTools.map((tool) => tool.name));
+            for (const tool of granted) {
+                if (!known.has(tool)) {
+                    throw new Error(`ConnectaConfig.pools.${name}: connector "${id}" has no tool "${tool}"`);
+                }
+            }
+        }
+        resolved.set(name, { access, grant: pool.grant ?? (() => false) });
+    }
+    return resolved;
+}
 /**
  * One-time construction warnings for deployment shapes that run fine but are
  * usually unintended. Warning-only — never throws and never changes behavior;
@@ -269,6 +332,7 @@ export function createConnecta(config) {
         maxResultBytes: config.calls?.maxResultBytes,
     });
     const inboundAuth = configuredAuth;
+    const pools = resolvePools(config.pools, registry);
     warnInsecureConfig(config, inboundAuth, logger);
     const requestAdmission = admissionController(config.admission?.requests, REQUEST_ADMISSION_DEFAULTS);
     const configuredCodeAdmission = admissionController(config.admission?.code, CODE_ADMISSION_DEFAULTS);
@@ -290,6 +354,7 @@ export function createConnecta(config) {
         registry,
         auth: inboundAuth,
         identity: config.identity,
+        pools,
         publicUrl: config.publicUrl,
         serverInfo,
         logger,

package/dist/registry.d.ts

@@ -114,8 +114,15 @@ export interface RegistryView {
     /** Bind returned OAuth state to this view's personal storage partition. */
     bindOAuthHandoff(id: string, authorizationUrl: string): Promise<void>;
 }
+/**
+ * Connector id → the only tool names this view may see on it. A connector
+ * absent from the map is visible whole. Derived from `connectorAccess`
+ * addresses at the auth gate; never from caller input.
+ */
+export type ToolAccess = ReadonlyMap<string, ReadonlySet<string>>;
 export interface RegistryScope {
     connectorIds: "all" | readonly string[];
+    toolAccess?: ToolAccess;
     subjectKey?: string;
     principalKey?: string;
 }
@@ -151,11 +158,20 @@ export declare class Registry implements RegistryView {
     readonly maxResultBytes: number;
     private readonly configuredConnectors;
     private readonly personalRegistries;
+    /** `connector.tool` grants that matched nothing, warned once per isolate. */
+    private readonly warnedAbsentGrants;
     constructor(connectors: Connector[], opts: RegistryOptions);
     personalRegistry(principalKey: string): Registry;
     /** Build the only connector view an authenticated request receives. */
     scoped(scope: RegistryScope): RegistryView;
     scopedStorage(subjectKey: string): KVStorage;
+    /**
+     * A granted `connector.tool` address the live catalog does not contain is
+     * unreachable, which is the fail-closed outcome; this only makes the
+     * misconfiguration visible. Remote catalogs load lazily, so construction
+     * cannot check it, and a catalog that drifts later cannot widen a grant.
+     */
+    noteAbsentGrant(connectorId: string, toolName: string): void;
     private oauthHandoffKey;
     storeOAuthHandoff(connectorId: string, state: string, principalKey: string): Promise<void>;
     oauthCallbackView(connectorId: string, state: string | null): Promise<{

package/dist/registry.js

@@ -119,6 +119,8 @@ export class Registry {
     maxResultBytes;
     configuredConnectors;
     personalRegistries = new Map();
+    /** `connector.tool` grants that matched nothing, warned once per isolate. */
+    warnedAbsentGrants = new Set();
     constructor(connectors, opts) {
         this.opts = opts;
         this.configuredConnectors = [...connectors];
@@ -201,6 +203,22 @@ export class Registry {
     scopedStorage(subjectKey) {
         return namespaced(this.opts.storage, `subject:${subjectKey}:`);
     }
+    /**
+     * A granted `connector.tool` address the live catalog does not contain is
+     * unreachable, which is the fail-closed outcome; this only makes the
+     * misconfiguration visible. Remote catalogs load lazily, so construction
+     * cannot check it, and a catalog that drifts later cannot widen a grant.
+     */
+    noteAbsentGrant(connectorId, toolName) {
+        const key = `${connectorId}.${toolName}`;
+        if (this.warnedAbsentGrants.has(key))
+            return;
+        this.warnedAbsentGrants.add(key);
+        // Grant names are operator data but may carry any non-control character;
+        // quote them so a line terminator a log reader honours cannot forge a line.
+        const quoted = JSON.stringify(key).replace(/[\u2028\u2029]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16)}`);
+        this.opts.logger.warn(`connectorAccess grants ${quoted} but connector "${connectorId}" lists no such tool; the grant is unreachable`);
+    }
     oauthHandoffKey(connectorId, stateHash) {
         return `oauth-handoff:v1:${connectorId}:${stateHash}`;
     }
@@ -1078,12 +1096,27 @@ class ScopedRegistryView {
         const connector = this.getConnector(parsed.connectorId);
         return connector ? { connector, toolName: parsed.toolName } : null;
     }
-    getTools(...args) {
+    async getTools(...args) {
         const registry = this.registryFor(args[0]);
         if (!registry) {
-            return Promise.reject(new Error(`Unknown connector "${args[0]}"`));
+            throw new Error(`Unknown connector "${args[0]}"`);
+        }
+        const tools = await registry.getTools(...args);
+        const granted = this.scope.toolAccess?.get(args[0]);
+        if (!granted)
+            return tools;
+        // Every consumer — search, describe, call_tool, and a program's
+        // connecta.call — resolves through this list, so an ungranted tool is
+        // indistinguishable from one the connector never had.
+        const visible = tools.filter((tool) => granted.has(tool.name));
+        if (visible.length < granted.size) {
+            const present = new Set(visible.map((tool) => tool.name));
+            for (const name of granted) {
+                if (!present.has(name))
+                    this.root.noteAbsentGrant(args[0], name);
+            }
         }
-        return registry.getTools(...args);
+        return visible;
     }
     contextFor(...args) {
         const registry = this.registryFor(args[0]);

package/dist/routes/credentials.js

@@ -81,6 +81,7 @@ async function handleCredentialRequest(context, connectorId, action) {
         validateAuthPermissions(authz, opts.registry);
         registry = opts.registry.scoped({
             connectorIds: authz.connectorIds,
+            ...(authz.toolAccess ? { toolAccess: authz.toolAccess } : {}),
             ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}),
             ...(authz.principalKey ? { principalKey: authz.principalKey } : {}),
         });

package/dist/routes/mcp.js

@@ -2,9 +2,10 @@ import { createMcpHandler, isLegacyRequest, McpServer, WebStandardStreamableHTTP
 import { registerExecuteTool } from "../execute.js";
 import { ExecutorAdmissionError, } from "../executor-admission.js";
 import { registerMetaTools } from "../meta-tools.js";
+import { intersectAccess } from "../connector-access.js";
 import { instructionsFor } from "../skills.js";
 import { msg } from "../errors.js";
-import { authorize, mayManageConnector, validateAuthPermissions, } from "./shared.js";
+import { authorize, loggableValue, mayManageConnector, validateAuthPermissions, } from "./shared.js";
 export const MCP_CORS_HEADERS = {
     "Access-Control-Allow-Origin": "*",
     "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
@@ -262,8 +263,10 @@ export function createMcpRoute(opts) {
     };
     return async function routeMcp(context) {
         const { path, request, baseUrl, runtimeContext, } = context;
-        if (path !== "/mcp")
+        const poolPath = /^\/mcp\/([a-z0-9_-]+)$/.exec(path);
+        if (path !== "/mcp" && !poolPath)
             return null;
+        const poolName = poolPath?.[1];
         let admission;
         try {
             admission = await opts.requestAdmission.acquire({
@@ -295,11 +298,37 @@ export function createMcpRoute(opts) {
             if (!authz.ok) {
                 return releaseAdmissionWithResponse(withMcpCors(authz.response), admission, request.signal);
             }
+            // A pool endpoint narrows the identity's own view and nothing else. An
+            // undeclared name, a grant that refuses, and a grant that throws are
+            // one identical 404 so a credential never enumerates the other pools;
+            // the operator log is where the reason lives.
+            let access = authz;
+            if (poolName !== undefined) {
+                const pool = opts.pools?.get(poolName);
+                let granted = false;
+                let reason = "undeclared";
+                if (pool) {
+                    try {
+                        granted = (await pool.grant(authz.identity)) === true;
+                        reason = granted ? "granted" : "refused";
+                    }
+                    catch {
+                        reason = "grant threw";
+                    }
+                }
+                if (!pool || !granted) {
+                    opts.logger.warn(`[connecta] refused /mcp/${poolName} with 404: pool ${reason}` +
+                        (authz.actor.id ? ` for ${loggableValue(authz.actor.id)}` : ""));
+                    return releaseAdmissionWithResponse(withMcpCors(new Response("Not Found", { status: 404 })), admission, request.signal);
+                }
+                access = intersectAccess(authz, pool.access);
+            }
             let scopedRegistry;
             try {
                 validateAuthPermissions(authz, opts.registry);
                 scopedRegistry = opts.registry.scoped({
-                    connectorIds: authz.connectorIds,
+                    connectorIds: access.connectorIds,
+                    ...(access.toolAccess ? { toolAccess: access.toolAccess } : {}),
                     ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}),
                     ...(authz.principalKey ? { principalKey: authz.principalKey } : {}),
                 });

package/dist/routes/oauth-management.js

@@ -14,6 +14,7 @@ async function handleOAuthManagementRequest(context, connectorId) {
         validateAuthPermissions(authz, opts.registry);
         registry = opts.registry.scoped({
             connectorIds: authz.connectorIds,
+            ...(authz.toolAccess ? { toolAccess: authz.toolAccess } : {}),
             ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}),
             ...(authz.principalKey ? { principalKey: authz.principalKey } : {}),
         });

package/dist/routes/shared.d.ts

@@ -4,7 +4,8 @@ import type { ActivityActor, ActivityReadGate, ActivityStore } from "../activity
 import type { CredentialVault } from "../credential-contract.js";
 import type { DeferredWork } from "../connector-scope.js";
 import type { AdmissionController } from "../executor-admission.js";
-import type { Registry } from "../registry.js";
+import type { Registry, ToolAccess } from "../registry.js";
+import type { ResolvedPool } from "../connector-access.js";
 import type { AuthenticatedIdentity, ConnectaBranding, Executor, InboundAuth, InboundAuthRuntimeContext, Logger } from "../types.js";
 import type { ConnectorPermission, ConnectaIdentityConfig } from "../index.js";
 export { msg } from "../errors.js";
@@ -12,6 +13,8 @@ export interface ServerOptions {
     registry: Registry;
     auth: InboundAuth[];
     identity?: ConnectaIdentityConfig | undefined;
+    /** Validated named pools served at `/mcp/<name>`; empty when none declared. */
+    pools?: ReadonlyMap<string, ResolvedPool> | undefined;
     publicUrl?: string | undefined;
     serverInfo: Implementation;
     logger: Logger;
@@ -78,6 +81,8 @@ export declare function authorize(request: Request, baseUrl: string, auth: Inbou
     subjectKey?: string;
     principalKey?: string;
     connectorIds: "all" | readonly string[];
+    /** Per-connector tool allowlist for connectors granted by address only. */
+    toolAccess?: ToolAccess;
     operator: boolean;
     credentialAdministration: ConnectorPermission;
     personalConnection: ConnectorPermission;

package/dist/routes/shared.js

@@ -1,3 +1,4 @@
+import { parseConnectorAccess } from "../connector-access.js";
 import { identityStorageKey, validIdentityReference } from "../identity.js";
 export { msg } from "../errors.js";
 export function privateJson(body, init = {}) {
@@ -33,11 +34,9 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
     if (auth.length === 0) {
         const actor = { kind: "anonymous" };
         const identity = { actor, interactive: false };
-        let connectorIds = "all";
+        let access;
         try {
-            connectorIds = identityConfig?.connectorAccess ? await identityConfig.connectorAccess(identity) : "all";
-            if (connectorIds !== "all" && (!Array.isArray(connectorIds) || !connectorIds.every(id => typeof id === "string" && /^[a-z0-9_-]+$/.test(id))))
-                throw new Error("invalid connector permission");
+            access = parseConnectorAccess(identityConfig?.connectorAccess ? await identityConfig.connectorAccess(identity) : "all");
         }
         catch {
             return {
@@ -45,7 +44,7 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
                 response: privateJson({ error: "identity access resolution failed" }, { status: 403 }),
             };
         }
-        return { ok: true, actor, identity, connectorIds, operator: false, credentialAdministration: "none", personalConnection: "none" };
+        return { ok: true, actor, identity, ...access, operator: false, credentialAdministration: "none", personalConnection: "none" };
     }
     let lastResponse = null;
     for (const provider of auth) {
@@ -77,21 +76,21 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
             let operator = interactive;
             let credentialAdministration = "none";
             let personalConnection = "none";
-            let connectorIds = "all";
+            let access;
             try {
                 if (identityConfig?.activityAccess) {
                     operator = interactive && principal
                         ? await identityConfig.activityAccess(principal)
                         : false;
                 }
-                connectorIds = identityConfig?.connectorAccess ? await identityConfig.connectorAccess(identity) : "all";
+                access = parseConnectorAccess(identityConfig?.connectorAccess ? await identityConfig.connectorAccess(identity) : "all");
                 if (interactive) {
                     credentialAdministration = identityConfig?.credentialAdministration ? await identityConfig.credentialAdministration(identity) : "none";
                     personalConnection = principal && identityConfig?.personalConnection ? await identityConfig.personalConnection(identity) : "none";
                 }
                 if (typeof operator !== "boolean")
                     throw new Error("invalid activity permission");
-                for (const permission of [connectorIds, credentialAdministration, personalConnection]) {
+                for (const permission of [credentialAdministration, personalConnection]) {
                     if (permission !== "all" && permission !== "none" && (!Array.isArray(permission) || !permission.every(id => typeof id === "string" && /^[a-z0-9_-]+$/.test(id))))
                         throw new Error("invalid identity permission");
                 }
@@ -112,7 +111,7 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
                 ...(principal && partitionIdentity
                     ? { principalKey: await identityStorageKey(principal) }
                     : {}),
-                connectorIds,
+                ...access,
                 credentialAdministration,
                 personalConnection,
                 operator,

package/dist/routes/ui.js

@@ -111,6 +111,7 @@ export async function routeUi(context) {
         validateAuthPermissions(authz, opts.registry);
         registry = opts.registry.scoped({
             connectorIds: authz.connectorIds,
+            ...(authz.toolAccess ? { toolAccess: authz.toolAccess } : {}),
             ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}),
             ...(authz.principalKey ? { principalKey: authz.principalKey } : {}),
         });
@@ -133,7 +134,7 @@ export async function routeUi(context) {
         const connector = registry.getConnector(detail[1]);
         if (!connector)
             return privateJson({ error: "unknown connector" }, { status: 404 });
-        const one = opts.registry.scoped({ connectorIds: [connector.id], ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}), ...(authz.principalKey ? { principalKey: authz.principalKey } : {}) });
+        const one = opts.registry.scoped({ connectorIds: [connector.id], ...(authz.toolAccess ? { toolAccess: authz.toolAccess } : {}), ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}), ...(authz.principalKey ? { principalKey: authz.principalKey } : {}) });
         const data = await buildUiData(one, baseUrl, opts.serverInfo, opts.credentialVault, activityEnabled, credentialManagement, defer, false, 1, authz.principalKey, { mayManage, timeoutMs: opts.probeTimeoutMs ?? 30_000, signal: request.signal });
         return privateJson({ ...data.connectors[0], permissions: permissions(connector) });
     }

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.24.1";
+export declare const CONNECTA_VERSION = "0.24.2";

package/dist/version.js

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.24.1";
+export const CONNECTA_VERSION = "0.24.2";

package/documentation/architecture.md

@@ -71,7 +71,7 @@ read top to bottom.
 | 3 | `/.well-known/*` | Auth metadata, or 404. |
 | 4 | `/health` | Open payload-free health, executor, admission, and deployment metadata; reserved routes reflect installed modules. |
 | 5 | `/oauth/callback/<connectorId>` | Core downstream OAuth completion, state verification and personal ownership checks; independent of UI. |
-| 6 | `/mcp` | Admission before auth, then a request-local MCP server. |
+| 6 | `/mcp`, `/mcp/<pool>` | Admission before auth, then a request-local MCP server. A pool path serves the declared pool intersected with the identity's own view; an undeclared name, a refusing grant, and a throwing grant are one identical 404. |
 | 7 | Other paths | 404. Custom HTTP routes belong to the deployment. |
 
 
@@ -80,7 +80,7 @@ policy, HSTS on HTTPS, while the UI module adds a nonce-based script CSP and fra
 and the exact refusal bodies; it exists because the ordering is invisible in
 any one file and a reordering reads like a harmless refactor.
 
-`/mcp` itself is five steps, in this order and for these reasons:
+`/mcp` itself is six steps, in this order and for these reasons:
 
 1. **Admit.** One permit from the deployment-wide FIFO pool, taken before auth
    so an unauthenticated flood costs a permit rather than a Clerk lookup
@@ -92,13 +92,18 @@ any one file and a reordering reads like a harmless refactor.
    only, and it warns at construction.
 3. **Derive the registry view.** Auth supplies a namespaced subject and, for a
    human, a principal. `identity.connectorAccess` selects declared connector
-   ids. Personal connectors use the principal partition; result paging uses
+   ids and, for a narrower slice, exact `connector.tool` addresses; the
+   scoped view filters every catalog read through them. Personal connectors use the principal partition; result paging uses
    the subject partition. No caller parameter selects either.
-4. **Refuse `?toolkit=`.** Caller-selected toolkits were removed ([#178](https://github.com/zackbart/connecta/issues/178))
+4. **Narrow to the pool.** On `/mcp/<pool>`, look the name up in the
+   declared pools and run its grant against the authenticated identity. The
+   view becomes the pool intersected with the identity's `connectorAccess`;
+   a pool can never widen it. Anything else is a 404 that names no pool.
+5. **Refuse `?toolkit=`.** Caller-selected toolkits were removed ([#178](https://github.com/zackbart/connecta/issues/178))
    but the URLs naming them were handed out, so the parameter is a 404 rather
    than silently serving the full registry. Retiring a scoping boundary into
    fail-open is the one outcome worse than the 404.
-5. **Serve.** A fresh `McpServer` per request, the seven meta-tools registered
+6. **Serve.** A fresh `McpServer` per request, the seven meta-tools registered
    against the registry and the response
    handed back.
 

package/documentation/auth.md

@@ -13,10 +13,77 @@ such as `get_result` pages. The principal is the human owner of personal
 connector auth. An interactive Clerk or Access user supplies all three. A
 Cloudflare service identity has an actor and subject but no principal.
 
-`identity.connectorAccess` returns `"all"` or declared connector ids. It governs
-discovery and use, and defaults to all connectors. Visibility alone grants no
-authentication-management permission. Two independent resolvers return
-`"all"`, `"none"`, or declared connector ids:
+`identity.connectorAccess` returns `"all"` or a list of grants. A grant is a
+declared connector id, which opens every tool on it, or a `connector.tool`
+address, which opens that tool alone. Grants are additive, so a bare id beside
+addresses for the same connector means the whole connector. It governs
+discovery and use, and defaults to all connectors.
+
+Tool grants are enforced in the scoped registry view, below the catalog
+service, so `search_tools`, `describe_tools`, both call tools, a program's
+`connecta.search` and `connecta.call`, and the connection UI all read the same
+filtered list. An ungranted tool fails exactly like one the connector never
+had: `unknown_tool`, with no hint that it exists. That is the whole security
+claim, and it lives in one place on purpose. There is no separate endpoint per
+tool set; an identity that should see a narrower slice is a branch in this
+resolver, and a bot that needs its own slice is its own bearer subject.
+
+## Pools
+
+A pool is a named slice of the deployment served at its own endpoint,
+`/mcp/<pool>`, for the case where one identity needs different capability
+sets on different clients: a support agent that sees three Notion tools and
+Linear, a calendar bot that sees one tool, both over the same credentials and
+catalog cache.
+
+```ts
+createConnecta({
+  pools: {
+    support: {
+      tools: ["linear", "notion.search_pages", "notion.fetch_page"],
+      grant: ({ principal }) => supportTeam.has(principal?.id ?? ""),
+    },
+    calendar_bot: {
+      tools: ["calendar.create_event"],
+      grant: ({ actor }) => actor.id === "calendar-bot",
+    },
+  },
+  identity: { connectorAccess },
+  connectors,
+  executor,
+});
+```
+
+The rules, each of which is a test:
+
+- **A pool narrows; it never widens.** The view on `/mcp/<pool>` is the pool
+  intersected with the identity's own `connectorAccess`. Plain `/mcp` is
+  unchanged. The security boundary is still the resolver; the pool decides
+  which part of it a given client sees.
+- **Grant defaults to deny.** A pool with no `grant` serves nobody. Only a
+  literal `true` admits; any other return, a throw, and an undeclared pool
+  name produce one 404 identical in status, body, and headers, so a
+  credential does not enumerate the other pools by response. Keep grants
+  pure and fast: a grant that does I/O is the one thing that could make a
+  declared pool distinguishable from an undeclared one by timing. The
+  operator log carries the reason.
+- **Structural mistakes throw at construction.** A malformed name, an
+  unknown connector, an empty pool, and a `connector.tool` address an
+  `api()` connector's static catalog lacks all refuse to boot. Remote
+  catalogs load lazily, so their addresses are checked at load and stay
+  unreachable until they match.
+- **OAuth discovery follows the path.** On Clerk, the 401 challenge for
+  `/mcp/<pool>` names `/.well-known/oauth-protected-resource/mcp/<pool>`,
+  whose `resource` is the pool URL, so RFC 9728 clients see a match.
+  Cloudflare Managed OAuth is application-level and needs nothing.
+
+A `connector.tool` address the live catalog does not contain is unreachable
+and warned once per isolate. Remote catalogs load lazily, so construction
+cannot check it, and a catalog that drifts later can never widen a grant
+because there is no wildcard: every tool grant is an exact name.
+
+Visibility alone grants no authentication-management permission. Two
+independent resolvers return `"all"`, `"none"`, or declared connector ids:
 
 - `credentialAdministration` allows an interactive human to manage shared
   credentials and shared OAuth grants.
@@ -39,8 +106,12 @@ administrator role or token-management authority.
 createConnecta({
   auth: cloudflareAccessAuth(),
   identity: {
-    connectorAccess: ({ principal }) =>
-      principal?.id === "owner-id" ? "all" : ["shared_docs", "personal_linear"],
+    connectorAccess: ({ principal, actor }) =>
+      principal?.id === "owner-id"
+        ? "all"
+        : actor.id === "calendar-bot"
+          ? ["calendar.create_event"]
+          : ["shared_docs", "personal_linear", "notion.search_pages"],
     credentialAdministration: ({ principal }) =>
       principal?.id === "owner-id" ? "all" : "none",
     personalConnection: () => ["personal_linear"],

package/documentation/operations.md

@@ -84,6 +84,7 @@ optional.
 | `executor` | — (required) | the sandbox `execute_code` runs in ([code mode](./code-mode.md#what-an-executor-must-implement)) |
 | `auth?` | none ⇒ open (dev only) | one `InboundAuth` or an array; bearer providers are checked before interactive providers ([inbound auth](./auth.md)) |
 | `identity?` | all visible; auth management denied; interactive activity reads | `{ connectorAccess?, credentialAdministration?, personalConnection?, activityAccess? }` derives separate use and management permissions ([identity](./auth.md#principals-visibility-and-operators)) |
+| `pools?` | none | `{ <name>: { tools, grant? } }` named slices served at `/mcp/<name>`, each intersected with the identity view and denied unless `grant` admits ([pools](./auth.md#pools)) |
 | `storage?` | `memoryStorage()` | connector state, catalogs, and result paging; pass storage explicitly to the optional vault ([storage](./storage-and-credentials.md)) |
 | `publicUrl?` | per-request origin | public base URL; an HTTPS value also redirects inbound HTTP |
 | `logger?` | `console`, prefixed `[connecta]` | `{ debug, info, warn, error }`, or `"silent"` to suppress diagnostic output; independent of activity history |
@@ -251,7 +252,7 @@ in.
 | `executor-admission.test.ts` | the portable bounded FIFO both pools use: active and queue ceilings, stable retryable overload, queue timeout, cancellation removal, idempotent release, shutdown |
 | `guarded-fetch.test.ts` | the guarded transport — construction, request building, destination confinement, and response handling |
 | `guest-api-contract.test.ts` | the shared guest contract on the Dynamic Worker, including caught call, typed inline describe recovery, discovery, utility, parallel-call, and budget failure codes; plus the real authority boundary — local `data:` fetch, denied egress, unresolved DNS, empty environment paths, unavailable filesystem/HTTP builtins, and present runtime globals |
-| `identity-scope.test.ts` | identity-derived connector visibility, personal credential isolation, separate shared-auth and personal-auth management permissions, and personal OAuth callback ownership |
+| `identity-scope.test.ts` | identity-derived connector visibility, named pools at `/mcp/<pool>` (grant-gated, intersected with the identity ceiling, identical 404 for undeclared, refused, and throwing grants, construction-time refusals), exact `connector.tool` grants enforced identically across discovery, direct calls, the program host bridge, and the connection UI, fail-closed grant parsing, the once-per-isolate absent-grant warning, personal credential isolation, separate shared-auth and personal-auth management permissions, and personal OAuth callback ownership |
 | `linear-provider.test.ts` | the Linear proxy's construction, guide, plan-aware catalog superset, and current workspace, template, and issue-sharing classifications |
 | `meta-tools-call.test.ts` | registry-backed calls: structured errors, truncation and `get_result`, per-connector result bounds, JSON representation failures, MCP content bounds, and offset alignment |
 | `meta-tools-search.test.ts` | registry-backed discovery: bounded search with page and address maxima, compact and JSON schemas with constraints, typed describe recovery and suggestions, and structured-result compatibility |

package/documentation/upgrading.md

@@ -117,7 +117,7 @@ exist so far:
 | --- | --- | --- |
 | **pre-template** | before 0.10.2 | no `connecta init` existed; hand-written, or copied from the retired `examples/node` |
 | **A** | 0.10.2 – 0.15.1 | `.env.example`, `.gitignore`, `AGENTS.md`, `CLAUDE.md`, `README.md`, `package.json`, `src/index.ts`, `tsconfig.json` |
-| **B** | 0.16.0 – 0.24.1 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
+| **B** | 0.16.0 – 0.24.2 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
 
 Generation A is a decade in template years and identifying it precisely does
 not matter, because you are about to reconstruct it exactly rather than guess
@@ -190,7 +190,7 @@ Generate the *current* template beside the base you already made, into the same
 `$SCRATCH`:
 
 ```sh
-(cd "$SCRATCH" && npx @zackbart/connecta@0.24.1 init current)
+(cd "$SCRATCH" && npx @zackbart/connecta@0.24.2 init current)
 ```
 
 You now have a three-way merge with a real base: `$SCRATCH/base` is what this
@@ -246,7 +246,7 @@ A deployment older than 0.10.2 has no base to diff against. Do not try to
 manufacture one. Instead:
 
 1. `SCRATCH=$(mktemp -d)`, then
-   `(cd "$SCRATCH" && npx @zackbart/connecta@0.24.1 init current)` — there is no
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.24.2 init current)` — there is no
    `base` leg here, only the current template to read from.
 2. Copy `$SCRATCH/current` into the deployment file by file, **skipping
    `src/index.ts`**.
@@ -267,7 +267,7 @@ first, so cross them bottom-up: start at the oldest one still above this
 deployment's pin and work back up the page, because each boundary assumes the
 older ones are already done.
 
-### 0.23.0 → 0.24.1
+### 0.23.0 → 0.24.2
 
 Use the [optional-module migration](./optional-modules-upgrade.md) to select
 modules, grant auth-management permissions, and migrate issued-token clients.
@@ -275,7 +275,9 @@ Preserve storage, encryption keys, and identity namespaces. 0.24.1 adds two
 optional settings, `execute.maxHostCalls` and `execute.hostCallTimeoutMs`, for
 deployments whose providers legitimately run past the 20-call and 15-second
 `execute_code` defaults, and one bounded `warn` log line per failed connector
-call; neither needs migration.
+call; neither needs migration. 0.24.2 adds tool-level
+`connectorAccess` grants and optional named pools at `/mcp/<pool>`; a
+deployment that declares neither is unchanged. See [pools](./auth.md#pools).
 
 ### 0.22.3 → 0.23.0
 

package/ethos.md

@@ -60,7 +60,7 @@ subsystem guides and the CHANGELOG.
 | `connecta.batch` | removed | JavaScript promises suffice |
 | Automatic direct-call retries | removed | callers own retry timing |
 | Connector HTTP routes | removed | deployments own custom routes |
-| Caller-selected toolkits | removed | only config may derive an identity's connector view ([#178](https://github.com/zackbart/connecta/issues/178)) |
+| Caller-selected toolkits | removed | config derives every view; config-declared, grant-gated pools at `/mcp/<pool>` are not caller-selected ([#178](https://github.com/zackbart/connecta/issues/178), [#531](https://github.com/zackbart/connecta/issues/531)) |
 | Proactive credential liveness | removed | fail-at-use is enough ([#179](https://github.com/zackbart/connecta/issues/179)) |
 | Classic (executor-free) surface | removed | an executor is mandatory ([#273](https://github.com/zackbart/connecta/issues/273)) |
 | Per-result lexical query coverage | removed | did not earn its response bytes in a precommitted gate ([#323](https://github.com/zackbart/connecta/issues/323)) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.24.1",
+  "version": "0.24.2",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",

package/templates/node/package.json

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.24.1",
+    "@zackbart/connecta": "0.24.2",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {