# Sub catalogs

**Sub catalogs** enable sharing private [catalogs](/docs/ai-control-plane/connect/sources/catalog/overview) with other organizations. This is useful when distributing internal MCP tools to partners, customers, or other teams within a company that operate as separate Gram organizations.

## The peered organization model

Gram uses a **super/sub organization** model to manage cross-organization catalog sharing:

- The **super organization** owns the catalog and controls who can access it
- A **sub organization** is granted access to specific catalogs from the super organization

```txt
Super Organization
├── Catalog: "customer-success"
├── Catalog: "data-platform"
│
├── Peer: Sub Org A  →  granted: "customer-success"
└── Peer: Sub Org B  →  granted: "customer-success", "data-platform"
```

When a sub organization is granted access to a catalog, the catalog MCP servers appear alongside its own registries. From the sub organization's perspective, these shared catalogs are **sub catalogs** — read-only collections of tools provided by the parent organization.

## Setting up sub catalogs

### Step 1: Create a peer relationship

Before sharing catalogs, establish a peer relationship with the target organization. In the Gram dashboard:

- Navigate to **Settings**
- Under the **Peers** section, click **Add Peer**
- Enter the sub organization ID to create the relationship

<Callout title="Permissions" type="info">
  Only the super organization can create peer relationships. The sub organization does not need to approve the peering — but no catalogs are visible until access is explicitly granted.
</Callout>

### Step 2: Grant catalog access

Once a peer relationship exists, grant the sub organization access to specific catalogs:

- Navigate to **Catalogs** and select the catalog to share
- Under **Access**, click **Grant Access**
- Select the peered organization from the list

The sub organization will now see this catalog in its registry list and can browse the MCP servers.

### Step 3: Sub organization connects to catalog servers

From the sub organization dashboard, the granted catalog appears in the **Catalogs** view. From there:

- Browse the available MCP servers in the catalog
- View server details including available tools and descriptions
- Connect to servers using the standard MCP client configuration

## Managing access

### Revoking access

To remove a sub organization's access to a catalog:

- Navigate to the catalog in the dashboard
- Under **Access**, find the organization and click **Revoke**

The sub organization will immediately lose access to the catalog MCP servers.

### Removing a peer relationship

Deleting a peer relationship automatically revokes all catalog grants for that sub organization. Navigate to **Settings** > **Peers** and remove the peer.

## How sub catalog resolution works

When a sub organization lists available registries, Gram combines:

- **Own registries** — any external MCP registries configured by the organization
- **Own catalogs** — any internal catalogs published by the organization
- **Granted sub catalogs** — catalogs shared by super organizations through peering

This merged view means sub organizations can seamlessly use tools from their own projects alongside tools shared by partner organizations.

<Callout title="Read-only access" type="info">
  Sub organizations cannot modify catalogs shared with them. They can only browse and connect to the MCP servers within. To change the toolsets in a shared catalog, the super organization must update the catalog.
</Callout>

## Next steps

- Learn how to [create catalogs](/docs/ai-control-plane/connect/sources/catalog/overview) to organize toolsets
- Read about [controlling server visibility](/docs/ai-control-plane/distribute/mcp-servers) for fine-grained access control