content/manuals/ai/mcp-catalog-and-toolkit/profiles.md
{{< summary-bar feature_name="MCP Profiles" >}}
Profiles organize your MCP servers into named collections. Without profiles, you'd configure servers separately for every AI application you use. Each time you want to change which servers are available, you'd update Claude Desktop, VS Code, Cursor, and other tools individually. Profiles solve this by centralizing your server configurations.
A profile is a named collection of MCP servers with their configurations and settings. You select servers from the MCP Catalog (the source of available servers) and add them to your profiles (your configured server collections for specific work). Think of the catalog as a library of tools, and profiles as your toolboxes organized for different jobs.
Your "web-dev" profile might include GitHub, Playwright, and database servers. Your "data-analysis" profile might include spreadsheet, API, and visualization servers. Connect different AI clients to different profiles, or switch between profiles as you change tasks.
When you run the MCP Gateway or connect a client without specifying a profile, Docker MCP uses your default profile. If you're upgrading from a previous version of MCP Toolkit, your existing server configurations are already in the default profile.
Each profile maintains its own isolated collection of servers and configurations. Your "web-dev" profile might include GitHub, Playwright, and database servers, while your "data-analysis" profile includes spreadsheet, API, and visualization servers. Create as many profiles as you need, each containing only the servers relevant to that context.
You can connect different AI applications to different profiles. When you connect a client, you specify which profile it should use. This means Claude Desktop and VS Code can have access to different server collections if needed.
Profiles can be shared with your team. Push a profile to your registry, and team members can pull it to get the exact same server collection and configuration you use.
Your new profile appears in the profiles list.
Select a profile in the Profiles tab to view its details. The profile view has two tabs:
[!CAUTION] Removing a profile deletes all its server configurations and settings, and updates the client configuration (removes MCP Toolkit). This action can't be undone.
When you run the MCP Gateway or use MCP Toolkit without specifying a profile,
Docker MCP uses a profile named default, or an empty configuration if a
default profile does not exist.
If you're upgrading from a previous version of MCP Toolkit, your existing
server configurations automatically migrate to the default profile. You don't
need to manually recreate your setup - everything continues to work as before.
You can always specify a different profile using the --profile flag with the
gateway command:
$ docker mcp gateway run --profile web-dev
Profiles contain the MCP servers you select from the catalog. Add servers to organize your tools for specific workflows.
You can add servers to a profile in two ways.
From the Catalog tab:
From within a profile:
If a server requires OAuth authentication, you're prompted to authorize it. See OAuth authentication for details.
Select a profile in the Profiles tab to see all servers it contains.
Some servers require configuration beyond authentication. Configure server settings within your profile.
OAuth credentials are shared across all profiles. When you authorize access to a service like GitHub or Notion, that authorization is available to any server in any profile that needs it.
This means all profiles use the same OAuth credentials for a given service. If you need to use different accounts for different projects, you'll need to revoke and re-authorize between switching profiles.
See OAuth authentication for details on authorizing servers.
Profile configurations persist in your Docker installation. When you restart Docker Desktop or your system, your profiles, servers, and configurations remain intact.
Profiles can be shared with your team by pushing them to OCI-compliant registries as artifacts. This is useful for distributing standardized MCP setups across your organization. Credentials are not included in shared profiles for security reasons. Team members configure OAuth separately after pulling.
registry.example.com/profiles/web-dev:v1).registry.example.com/profiles/team-standard:latest).The profile is downloaded and added to your profiles list. Configure any required OAuth credentials separately.
A typical workflow for sharing profiles across a team:
registry.example.com/profiles/team-dev:v1).This ensures everyone uses the same server collection and configuration, reducing setup time and inconsistencies.
When you connect an AI client to the MCP Gateway, you specify which profile's servers the client can access.
Connect clients to your profile through the Clients section in the MCP Toolkit. You can add clients when creating a profile or add them to existing profiles later.
When setting up a client manually, you can specify which profile the client uses. This lets different clients connect to different profiles.
For example, your Claude Desktop configuration might use:
{
"mcpServers": {
"MCP_DOCKER": {
"command": "docker",
"args": ["mcp", "gateway", "run", "--profile", "claude-work"]
}
}
}
While your VS Code configuration uses a different profile:
{
"mcp": {
"servers": {
"MCP_DOCKER": {
"command": "docker",
"args": ["mcp", "gateway", "run", "--profile", "vscode-dev"],
"type": "stdio"
}
}
}
}
To switch the profile your clients use, update the client configuration to
specify a different --profile value in the gateway command arguments.