Profiles

Introduction

Profiles allow you to provide a specific set of servers and credentials for specific agents and use-cases. Examples:

• GitHub Copilot Agent
• Common Software Engineer IDE
• Invoicing Agent

Technically, profile features are:

• Override credentials for specific servers
• Optionally restrict available servers for a session
• Be applied conditionally

When applied, profiles always take precedence over any user-scoped and server-scoped credentials. Multiple profiles can be active at the same time. A profile can be applied by:

• assigning it to your personal access token (PAT) and using this PAT to connect to the gateway
• setting a querystring parameter on your Gatana MCP URL: https://YOUR_ORG_ID.gatana.ai/mcp?p=PROFILE_ID (for multiple profiles, use comma-separated IDs: ?p=PROFILE1,PROFILE2)
• sending a special header: x-gatana-profile-id: PROFILE_ID (for multiple profiles, use comma-separated IDs)
• claim mappings from your external identity provider (see below) - multiple mappings can match simultaneously

Managing Profiles

Organization owners can create and manage profiles by going to Profiles in the right menu in Gatana Web App. 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. You should add at least one server to the profile, otherwise it will not be possible to call any tools when this profile is applied.

You can also manage profiles using the Gatana Public API.

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, or by assigning it to a PAT.
• Disabled: The profile can only be applied via claim mappings from an external identity provider. Users cannot manually select this profile or assign it to a PAT.

This is useful when you want to enforce that certain profiles are only applied based on attributes from your IdP, such as department or team membership.

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.

Tool Restrictions

For each server in a profile, you can optionally restrict which tools are available. This provides fine-grained control over tool access without needing to create separate server configurations.

To configure tool restrictions:

1. Go to the profile detail view
2. In the servers table, click the "All tools" button for a server
3. Select the specific tools you want to allow
4. Save your changes

Behavior:

• If no tools are selected for a server, all enabled tools from that server are available (default)
• If specific tools are selected, only those tools are available when the profile is applied
• Tool restrictions are independent of Restrictive Mode — they apply regardless of whether restrictive mode is enabled
• When multiple profiles are active, tool allowlists 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 it's in the profile's allowlist

This feature is useful for:

• Limiting an AI agent to only specific capabilities
• Creating specialized profiles for different use cases (e.g., read-only vs. full access)
• Gradually rolling out new tools by allowing them only in specific profiles first

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.

Examples

Consider the following claims from your IdP:

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

There are different ways of matching:

Credentials Resolution

When a tool is called, Gatana determines which credentials to use for the server 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.
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.