Group tools are unavailable when an MCP repository allowlist

Error message

Group tools are unavailable when an MCP repository allowlist is set.

What it means

Thrown by McpRepositoryPolicy.callTool when a repository allowlist is configured and the requested backend method starts with 'group_' (the cross-repo group tools). Allowlist mode restricts the server to its explicitly allowed local repositories, so the entire group-tool surface is disabled at the dispatch wrapper, before the backend is reached.

Source

Thrown at gitnexus/src/mcp/repository-policy.ts:263

        total,
        limit,
        offset,
        returned,
        hasMore,
        ...(hasMore && { nextOffset: offset + returned }),
      },
    };
  }

  private async callTool(
    backend: LocalBackend,
    method: string,
    params: Record<string, unknown> | undefined,
  ): Promise<unknown> {
    if (!this.configured) return backend.callTool(method, params);
    if (method === 'list_repos') return this.listReposPage(backend, params);
    if (this.restricted && method.startsWith('group_')) {
      throw new Error('Group tools are unavailable when an MCP repository allowlist is set.');
    }
    return backend.callTool(method, this.normalizeToolArgs(params));
  }

  private async resolveRepo(
    backend: LocalBackend,
    repo?: string,
    branch?: string,
  ): Promise<Awaited<ReturnType<LocalBackend['resolveRepo']>>> {
    if (!this.configured) return backend.resolveRepo(repo, branch);
    if (!this.restricted) return backend.resolveRepo(repo ?? this.defaultRepo?.path, branch);
    const selected = this.repoForArgs(repo === undefined ? undefined : { repo });
    return backend.resolveRepo(selected?.path, branch);
  }

  private async selectToolRepository(
    backend: LocalBackend,
    repo?: string,

View on GitHub (pinned to 52924ef12c)

Solutions

Replace group tool usage with per-repo calls against each allowed repository (query/context/impact per repo).
Use list_repos to enumerate what is available under the allowlist.
If group tools are required, remove GITNEXUS_MCP_ALLOWED_REPOS from the server environment.

Example fix

# before (allowlist set)
await client.callTool({ name: 'group_status', arguments: { group: 'org' } });

# after
for (const repo of ['frontend', 'backend']) {
  await client.callTool({ name: 'query', arguments: { search_query: 'status', repo } });
}

Defensive patterns

Strategy: validation

Validate before calling

function assertToolAllowedUnderAllowlist(tool: string, allowlistConfigured: boolean) {
  if (allowlistConfigured && tool.startsWith('group_')) {
    throw new Error('Group tools are disabled by the repository allowlist on this endpoint.');
  }
}

Type guard

const isGroupTool = (tool: string): boolean => tool.startsWith('group_');

Try / catch

try {
  return await client.callTool({ name, arguments });
} catch (e) {
  if (e instanceof Error && e.message.includes('Group tools are unavailable')) {
    return runPerRepo(name, arguments, allowedRepos); // fan out manually
  }
  throw e;
}

Prevention

Filter tool names through !name.startsWith('group_') when running against allowlisted servers.
Use list_repos to discover what the allowlist exposes instead of assuming group surfaces exist.
When adding an allowlist to a shared deployment, audit dashboards/jobs for group_* tool usage first.

When it happens

Trigger: GITNEXUS_MCP_ALLOWED_REPOS set (restricted), then invoking any group_* tool through MCP — e.g. the group status/contracts tool surface — via callTool. Note list_repos stays available and is intercepted separately.

Common situations: A multi-repo group deployment is later locked down with an allowlist for security/compliance, but dashboards or scheduled jobs still poll the group status tools. Client code enumerating all tools via tools/list and probing each one hits this on the group entries.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@52924ef12c (2026-08-20). Data as JSON: /api/errors/d3abbefd98629c48. Report an issue: GitHub.