Credentials

Introduction

Gatana splits authorization into two components:

• Authorization Configuration: describing what form credentials should have
• Credentials: the resolved tokens/values which will be passed when calling the tool

Gatana provides two authorization methods: OAuth2.1 and API Keys. The resulting credentials are available to be used in:

• Remote MCP URL (e.g. query-string parameter)
• HTTP headers
• Environment variables
• Command

They can be access by using the following expressions:

• API Keys: {{ credentials.keys.MY_API_KEY }}
• OAuth Access Token: {{ credentials.accesstoken }}

The credentials can be scoped to the server; meaning that all Gatana users share the same credentials when calling the tools, or they can be user-scoped; meaning that each user has their own credentials. Additionally, each profile can have their own set of credentials. See Profiles for more information

Tool Refresh Policy

You can control which credentials (if any) should be used for refreshing the tools for a server. The available options are:

• Server-Scoped Credentials: Use server-scoped credentials.
• Any Credentials: Use any credentials, i.e. default/server-, user- or profile-scoped.
• No Credentials: Do not use or require any credentials for tool refreshes. This is useful if the server does not require credentials for tool refreshes (e.g. OpenAPI servers, or any server that don't require authorization for tool listing), but does require them for tool-calling. It can simplify credential management by not requiring server-scoped credentials when user-scoped credentials are required.

Authorization Configuration

Gatana supports three methods of authorization for servers:

• No authorization: the server can always be used without requiring any authorization.
• OAuth 2.1: the server requires a bearer token which should be provded using OAuth 2.1.
• OAuth Client Credentials the server requires a bearer token which should be provded using OAuth Client Credentials grant.
• API Keys: one or more static key-value pairs which can be used in headers, command or environment variables.

API Keys

The configuration is a list of the key names which the credentials should provide. The resulting credentials is the key-value pairs of this list which is provided in a separate step. The values can be used in headers, command arguments and HTTP headers using this expression:

{{ credentials.keys.MY_API_KEY }}

OAuth 2.1

For OAuth 2.1, you must provide the authorization server and client details. Gatana supports automatic discovery of the authorization server and dynamic client registration, or manual input.

If the server is a remote server, you may use the Discover OAuth from remote MCP URL button to attempt to discover the OAuth details automatically. If your remote server does not support this. You can also provide the issuer URL and click the Discover button next to the Issuer input field to automatically discover the authorization server details.

If the issuer supports dynamic client registration, i.e. there is a Client registration endpoint provided, you can click the Auto button next to the Client ID input field, and Gatana will automatically register a OAuth client.

For almost all cases, the Authorization Code grant should be used. Gatana also supports the Device Code grant, note however that some issuers (e.g. Google) places limits the credentials privileges when using this device code grant.

OAuth Client Credentials

For OAuth Client Credentials, you must provide the only the authorization server metadata in the server settings. Each credential consist of a Client ID + Client Secret and optional scopes, which will be used to generate an access token.

Credentials

The credentials are the resolved values which will be used when communicating with the server. The credentials can be scoped as following:

• Server: there is one (1) set of credentials which will be used by all Gatana users accessing the tools of the server.
• User: each Gatana user has their own credentials. A common scenario could be a server for e-mail, where each Gatana user should only get access to their own mailbox.
• Profile: if the MCP session has a profile applied, and if the profile has a credential set for this server

Provide the Credentials

There are three ways of providing credentails, directly in the Gatana App, through MCP protocol, or the Gatana Public API.

Gatana App

Navigate to the server details, and click on the Credentials setting. On this page, you can provide your user-scoped credentials, and, if you have administration privileges for this server, you can also provide the the default credentials.

MCP Protocol

The other way of providing credentials is over the MCP protocol; when Gatana calls a server on-behalf of a Gatana user, it will look up any required credentials. If credentials are missing, Gatana will fail the request with a MCP response looking like this:

{
  errorCode: 'need-credentials',
  authorizeUrl: 'https://gatana.ai/api/v1/mcp-servers/oauth/gt_V1St_GX-R8/begin',
  message: 'This tool requires secondary authorization. You must tell the end-user to ' +
    'please go to the authorizeUrl. After this is done, you can retry the tool call and it will work.',
}

The MCP client, i.e. the agent, is at this point expected provide the authorizeUrl to the end-user. The page under the URL will ask the user to fill out the necessary API Key values, or redirect the user to the configured OAuth 2.1 server to authorize, depending on the authorization method. This is only requried once per user and the user does not need to sign-in to Gatana during this process since the authentication is implied by the token in the URL. The link is valid for 24 hours.

Gatana Public API

If you would like to apply your own logic, you can use the Gatana Public API directly. You can check if user has credentials, get the URL where user can authorize over OAuth, or set the credentials directly.

Limitations

Only default credentials are availble for used in environment variables and command. When deploying a non-remote server, any expression will expand to the default credentials.