Toolsets

A toolset registers an MCP server in DIAL Core, so agents and users can call its tools through DIAL. Core lists the server's tools, limits them to an allowed set, proxies tool calls, and handles sign-in to servers that need credentials. This reference covers registering toolsets in Core's configuration; it is for platform engineers who know how DIAL Core is configured.

To use toolsets in agents, see Toolsets in Quick Apps. DIAL Admin manages toolsets in Toolsets.

Where toolsets are defined

Source	Location
Config file	`toolsets.<name>`
Configuration API	`/v1/toolsets/platform/<name>`

Toolsets that users create or publish live in their own or the public bucket and are managed through the resource API. A toolset's name is a deployment ID and must match ^[A-Za-z0-9-_]+$.

Fields

Field	Description
`endpoint`	The MCP endpoint of the server.
`transport`	The transport the MCP server supports: `HTTP` or `SSE`.
`allowedTools`	The tools available from the server.
`displayName`	The name shown in DIAL clients, tables, and logs.
`description`	A short description of the toolset.
`intro`	A short onboarding text shown to users separately from `description`.
`iconUrl`	The URL of the icon shown for the toolset.
`descriptionKeywords`	Keywords that describe the toolset, for example `code-gen`.
`provider`	The vendor's name.
`vendorWebsite`	The vendor's website.
`author`	The toolset's developer.
`createdAt`, `updatedAt`	The dates the toolset was created and last updated.
`userRoles`	The roles, from identity provider claims or API keys, that may use the toolset. When unset, every user may use it.
`maxRetryAttempts`	The maximum number of attempts to route one request to the toolset's endpoint.
`forwardPerRequestKey`	When `true`, Core forwards a per-request API key to the endpoint, so the toolset can reach files in DIAL storage. Not allowed with `authentication_type: API_KEY`.
`forwardAuthToken`	When `true`, Core forwards the caller's authorization token to the endpoint, for pass-through authentication.
`auth_settings`	How users authenticate to the MCP server. See Authentication.

Authentication

auth_settings.authentication_type sets how users authenticate to the MCP server: OAUTH, API_KEY, or NONE.

OAuth with an existing client

Field	Required	Description
`client_id`	Yes	The OAuth client ID.
`client_secret`	For confidential clients	The client secret. Public clients that use PKCE leave it out. Stored encrypted and never returned; admins get `client_secret_hint`.
`redirect_uri`	No	Pins the toolset to one callback URL. When unset, the client gives `redirect_uri` at sign-in, and it must be listed in `toolsets.security.allowedRedirectUris`.
`authorization_endpoint`	When not discoverable	Where the user signs in. Can be discovered from the authorization server's `.well-known` metadata.
`token_endpoint`	When not discoverable	Where the authorization code is exchanged for a token. Can be discovered the same way.
`code_challenge_method`	With PKCE	The PKCE method, usually `S256`.

"auth_settings": {
  "authentication_type": "OAUTH",
  "client_id": "<CLIENT_ID>",
  "client_secret": "<CLIENT_SECRET>",
  "authorization_endpoint": "https://<AUTH_SERVER>/authorize",
  "token_endpoint": "https://<AUTH_SERVER>/token",
  "code_challenge_method": "S256"
}

OAuth with dynamic client registration

Leave out client_id and client_secret, and Core registers a client with the authorization server. When redirect_uri is unset, every URI in toolsets.security.allowedRedirectUris is registered; a callback URL missing from that list at registration cannot be used later without registering the client again.

"auth_settings": { "authentication_type": "OAUTH" }

API key and none

"auth_settings": { "authentication_type": "API_KEY", "api_key_header": "X-Api-Key" }

api_key_header is the header that carries the user's key. NONE means the server needs no authentication.

Users store their credentials with POST /v1/ops/toolset/signin and remove them with POST /v1/ops/toolset/signout. Each request names the toolset (url, for example toolsets/<bucket>/<path>), the authentication type, and the credentials level: GLOBAL, APP, or USER. An OAuth sign-in carries the authorization code; an API key sign-in carries api_key.

Deployments with more than one sign-in client, such as DIAL Chat and DIAL Admin, must set toolsets.security.allowedRedirectUris. OAuth and encryption settings are in Toolsets security.

Example

{
  "toolsets": {
    "git": {
      "endpoint": "http://git-mcp-server:8080/mcp",
      "transport": "HTTP",
      "allowedTools": ["branch", "remote"],
      "displayName": "Git",
      "description": "Browse and manage Git remotes and branches",
      "userRoles": ["developer"],
      "auth_settings": { "authentication_type": "NONE" }
    }
  }
}

Where toolsets are defined​

Fields​

Authentication​

OAuth with an existing client​

OAuth with dynamic client registration​

API key and none​

Sign-in and sign-out​

Example​

Further reading​