Profiles

Introduction

A profile can:

• Override credentials
• Restrict available servers and tools (see also Limiting Severs)
• Rename tools and promote tools so they stay visible in Code Mode
• Force Code Mode to be enabled

A profile can be enabled by:

• direct assignment to user, service account or a team
• setting a querystring parameter: https://gatana.ai/mcp?p=PROFILE_ID
• sending a header: x-gatana-profile-id: PROFILE_ID
• access token claims
• assigning it to your personal access token (PAT)
• attaching it to one of your OAuth clients

Creating Profiles

Organization owners can create and manage profiles by going to Profiles in the side menu. In this view you can see all existing profiles for your organization, and a button to create new profiles. In the detail view of a profile you can assign the servers which this profile has access to. Existing profiles can also be managed by their maintainers.

A profile automatically gets member-level permissions on each server assigned to it.

You can also manage profiles using the Gatana Public API.

Force Code Mode

When creating or editing a profile, you can set the Force Code Mode flag, when enabled Code Mode will be enabled for all sessions with this profile. Note that all servers, not only the ones assigned directly to the profile, will be covered by code mode. This means that you could for example create one profile which only forces code mode, without having any servers directly attached to it.

The Code Mode tools are served by the built-in codemode server, so setting the flag automatically adds that server to the profile and keeps it there while the flag is set. If the codemode server is not installed for your organization yet, saving the flag installs it. Installing a server for the whole organization requires owner permissions — a profile maintainer who is not an owner gets an error and must ask an administrator to install the server first.

Tools that a profile promotes stay listed next to the Code Mode tools.

Open to All Users

When creating or editing a profile, you can set the Open to All Users flag:

• Enabled: Any user in your organization can apply this profile using the p= query string parameter, the header, by assigning it to a PAT, by attaching it to one of their connected clients, or assigning themselves.
• Disabled: The profile can only be applied via direct user assignment or by claim mappings from an external identity provider.

Restrictive Mode

When enabled, sessions with the profile applied will only have access to the servers assigned to that profile. This is useful for limiting server availability in specific contexts, such as sub-agents or isolated workflows.

Configuring Tools

For each server in a profile, you can control which tools are available, expose tools under different names, and promote tools so they stay visible in Code Mode. This provides fine-grained control over tool access without needing to create separate server configurations.

To configure the tools of a server:

1. Go to the profile detail view
2. In the servers table, click Edit on the server row
3. Configure the tool selection, exposed names and promotions
4. Click Save Changes

The same page also manages the profile's credentials for that server.

Tool Selection

Use every tool of the server is enabled by default: every enabled tool of the server is available when the profile is applied. Turn it off to pick the tools yourself with Add tools — only the picked tools are then available.

While you pick the tools yourself, Add new tools automatically controls what happens when the server starts to report tools that did not exist before. When enabled, new tools join the selection automatically; when disabled, new tools stay unavailable until a maintainer adds them. Disable it to gradually roll out new tools, or to keep an AI agent limited to a fixed set of capabilities.

Behavior:

• Tool selection is independent of Restrictive Mode — it applies regardless of whether restrictive mode is enabled
• When multiple profiles are active, tool selections are combined (union) — if Profile A allows tool1 and Profile B allows tool2, both tools are available
• Server-level tool disabling always takes precedence — if a tool is disabled at the server level, it won't be available even if the profile selects it
• Removing a server from a profile discards the tool configuration for that server — if you add the server back later, it starts over with every tool enabled

Renaming Tools

Every tool has an Exposed Name — the name that MCP clients see and call. By default this is <server-slug>_<tool-name>. Rename a tool to give it a shorter or more task-specific name.

A renamed tool:

• is listed under the new name instead of its regular one
• stays callable under its regular <server-slug>_<tool-name> name as well
• must be named with letters, digits and hyphens only (up to 64 characters, no underscores), and the name must be unique within the profile

When two active profiles rename different tools to the same name, the profile with the highest priority keeps the name, and the other tool falls back to its regular name so it stays reachable.

Promoted Tools

A promoted tool stays listed when the session runs in Code Mode, next to the Code Mode tools. Use this to keep a few important tools directly callable while everything else is reached through execute_code.

Renaming and promoting are independent: you can rename a tool without promoting it, and promote a tool without renaming it.

Profile Maintainers

Every profile has a list of maintainers: the users who are allowed to manage that profile. Maintainers can:

• Edit the profile's name, description and flags (Open to All Users, Restrictive Mode, Force Code Mode)
• Add and remove servers, and configure their tools
• Manage the profile's credentials (configure API keys or authorize OAuth)
• Manage claim mappings and direct assignments
• Add and remove other maintainers
• Delete the profile

When a profile is created, its creator is automatically added as the first maintainer. Organization owners can always manage all profiles, regardless of the maintainer list.

To manage maintainers:

1. Go to the profile detail view
2. Under Maintainers, click Add Maintainer and select a user
3. To remove a maintainer, click the delete button on the corresponding row

A profile must always have at least one maintainer (the last maintainer cannot be removed).

Applying Profiles

Direct Assignment (User, Service Account or Team)

Profiles can be assigned directly on users, service accounts and teams. A user can assign profiles to their own account, and organizational owners can assign profiles to any account. For teams the same logic applied for team maintainers. Owners also have the possibility of assigning the profile in locked mode. This prevents the profile from being removed by users, and will take precedent in any credential resolution conflict.

To assign a profile to a user:

1. In Gatana, navigate to People & Accounts, click on the account
2. In the detail view, under Profiles click on Assign profile
3. Select the profile you would like to assign. If you are an organization owner, you can chose to add it in locked mode

To assign a profile to a team:

1. In Gatana, navigate to Team, click on the team
2. In the detail view, under Profiles click on Assign profile
3. Select the profile you would like to assign. If you are an organization owner, you can chose to add it in locked mode

Claim Mappings

Claim mappings allow you to automatically apply a profile based on claims from your external identity provider. When a user authenticates, Gatana checks their claims against configured mappings and applies the matching profile with the highest priority.

To configure claim mappings, go to the profile detail view and add mappings with a claim key and value.

Consider the following claims from your IdP:

{ 
  department: "engineering",
  groups: ["engineering", "platform-team"],
  branch: {
    office: "london"
  }
}

There are different ways of matching:

Personal Access Tokens

Profiles can also be assigned directly on to personal access token, either on a user's own PAT:s, or on a service account PAT:s. Only organization owner can manage service account PAT:s.

To assign a profile to your own PAT:

1. In Gatana, go to Clients & API Keys in the left sidebar
2. Under Personal access tokens, click Edit for one of your PAT:s
3. Select the profile(s) you would like to associate with the PAT

To assign a profile to a service account's PAT:

1. In Gatana, navigate to People & Accounts, click on the service account
2. In the detail view, under Personal Access Tokens click on Edit for one of the PAT:s
3. Select the profile(s) you would like to associate with the PAT

Connected Clients

Profiles can also be attached to a connected client, an app that signs in through OAuth instead of holding a token. The profiles are applied on every request that client makes, in addition to the profiles you already hold, the same way a PAT's profiles are.

To attach a profile to a connected client:

1. In Gatana, go to Clients & API Keys in the left sidebar
2. Under Clients, click Edit for the client
3. Select the profile(s) you would like to attach

You can attach the same profiles you could assign to a PAT: profiles that are open to all users or that you are otherwise allowed to manage. Disconnecting the client forgets the attachment.

Credentials Resolution

When a tool is called, Gatana determines which credentials to use in the following order:

1. Profile credentials - If any active profile has credentials configured for the server, those are used. When multiple profiles are active, they are checked in order and the first profile with valid credentials wins (see profile ordering below).
2. User credentials - If no profile has credentials and the server is configured for user-scoped credentials, the user's own credentials are used.
3. Server credentials - If neither profile nor user credentials are available, server-level shared credentials are used.

This allows you to share credentials across a group of users via profiles while still falling back to individual or shared credentials when needed.

Profile Ordering

When multiple profiles are active at the same time, they are evaluated in a fixed priority order. The first profile (in this order) that has valid credentials for the server wins:

1. Profiles directly assigned to the user in locked mode
2. Profiles directly assigned to one of the user's teams in locked mode
3. Profiles directly assigned to the user (not locked)
4. Profiles directly assigned to one of the user's teams (not locked)
5. All other profiles — e.g. applied via the p= query string parameter, the x-gatana-profile-id header, claim mappings, a personal access token, or a connected client

Within the same priority level, profiles are checked in a stable order (by profile name), so resolution is deterministic. In short: locked assignments always beat unlocked ones, and user assignments always beat team assignments at the same lock level.