Portal Toolset And Client Application Management

Purpose

This functional area controls how published mappings are packaged and exposed to actual AI consumers.

It connects mapping output to the client applications that are allowed to use it.

Main Capabilities

• create and manage MCP toolsets
• add one or more published mappings to a toolset
• select which of each mapping's endpoints are exposed as tools
• configure the downstream target system, authentication profile and default access policy per mapping
• define an optional default system prompt at toolset level
• configure request/response payload logging per toolset and per endpoint
• configure how correlation identifiers are propagated to downstream APIs per toolset
• assign toolsets to client applications
• manage tenant-scoped client applications
• define an optional client-level system prompt
• choose prompt composition per toolset assignment
• manage application API keys

Two Views Of The Same Data

Tools Management offers two views, switched with a toggle and remembered between visits:

• MCP Toolsets (the default) — one row per toolset, showing the mappings it draws from. This is where a toolset is created and mappings are added to it.
• Mappings — one card per published mapping, showing the toolsets that publish from it. This answers "what is exposed from this API?". A toolset that draws from several mappings appears under each of them, and its Mappings column shows how many mappings it touches — so it is clear that editing it affects more than the mapping whose card it was opened from.

Both are views of the same underlying configuration; neither is a subset of the other.

Tool Name Uniqueness Within A Toolset

An MCP tool is named {toolset}-{endpoint}, and an AI client invokes a tool by that name. Two mappings in the same toolset therefore cannot both expose an endpoint under the same external name — one tool would answer the other's calls.

The Portal refuses such a configuration when the toolset is saved, naming both mappings so the conflict can be resolved. Nothing is renamed automatically: renaming a published tool would move it underneath AI clients that already call it. Resolve it by renaming the endpoint in one of the mappings, or by putting those mappings in separate toolsets.

One path can introduce a duplicate without passing that check: republishing a mapping may rename an endpoint onto a name another mapping in the same toolset already uses. That republish is not blocked, because failing a mapping publish over the shape of an unrelated toolset would be the wrong trade. The condition is reported instead:

• the toolset carries a warning icon wherever it is listed
• opening it shows a banner naming the affected tool, and a warning badge on each colliding endpoint
• Tool Oversight shows a Duplicate name badge against the tools involved, for security reviewers who do not administer the toolset

Both tools remain callable until the conflict is resolved — which is the accurate state of affairs rather than a safeguard — and deselecting either endpoint clears it.

MCP Toolsets

Toolsets are the publication grouping used to expose mappings to AI clients. A toolset is what an AI client connects to, and it can draw its tools from one or more published mappings.

The workflow starts from the toolset: name it and — when the administrator's session is not scoped to a single tenant — choose the tenant it belongs to, then choose which client applications may reach it and add the mappings it should publish. Every mapping in a toolset belongs to one tenant: the toolset is reached through that tenant's runtime endpoint and its tools are governed by that tenant's policies, so the tenant is chosen before the first mapping and is fixed for as long as the toolset has one. Each added mapping is configured on its own — its downstream target system, its authentication profile, its default access policy, and which of its endpoints become tools — because a toolset spanning two APIs reaches two different systems.

Settings that belong to the toolset as a whole are the name and status, client access, the default system prompt, the schema discovery mode, payload logging and correlation propagation.

Client applications and mappings are both added through a searchable picker over what has not been added yet, and each one added can be removed again — including a toolset's last mapping, since a toolset with no mappings is simply refused when saved. Including an endpoint marks it as exposed without opening its settings; an expand control on the endpoint opens its per-endpoint overrides when they need reviewing.

Functionally, administrators can use toolsets to:

• bundle selected endpoints from several mappings into one discoverable set
• apply business-friendly tool naming
• maintain prompt-related metadata and default AI instructions
• decide which published functionality becomes visible at runtime

When a selected endpoint is exposed through a toolset, the Runtime presents the field names configured for AI consumption rather than the raw field names used internally. The original field names from the source API remain an internal implementation detail used only for translating requests and responses to and from the downstream API.

Toolsets can carry an optional default system prompt. This prompt becomes the base instruction set exposed to MCP-capable AI clients for the toolset.

System Prompt Composition

Prompt behavior is controlled across three layers:

• the toolset default system prompt
• the client application system prompt
• an optional assignment-specific custom system prompt

For each client application assigned to a toolset, administrators can choose whether the client application's own system prompt should participate in the effective prompt for that toolset.

They can also enable a custom prompt on the assignment and decide whether it should:

• append to the default prompt chain
• override the full default prompt chain

Functionally this allows:

• a shared toolset prompt for all consumers
• per-client default instructions when a client needs stable behavior across multiple toolsets
• toolset-specific per-client prompt customization when a single consumer needs special behavior for one toolset only

Endpoint Exposure

Not every endpoint in a mapping needs to become an exposed tool.

This area lets administrators decide:

• which endpoints are included
• how they are presented
• which runtime-visible tool identifiers are produced

This keeps the runtime catalog intentional and curated.

Schema Discovery Configuration

Toolset administrators can control how much schema detail is sent to AI clients during tools/list.

At toolset level, the Portal supports three schema discovery modes:

• Full — send the complete schema with descriptions and format hints
• Data Structure Only — send the real exposed schema structure but omit descriptions and format hints to reduce token cost
• Lazy — send only a placeholder schema and require discovery before invocation

Each included endpoint can override the toolset default. When no endpoint override is configured, the Runtime uses the toolset default for that endpoint automatically.

The toolset editor makes this explicit by showing the effective mode for each endpoint and by allowing endpoint overrides to be reset back to the toolset default in one action.

Discovery Guidance In Portal UX

The Portal guides administrators about the runtime impact of each discovery mode:

• Full favors immediate clarity at the highest token cost
• Data Structure Only remains compatible with standard MCP client binders because real parameter names and types are still sent
• Lazy is explicitly called out as requiring non-standard clients because standard MCP binders expect a real schema at discovery time

For endpoint-level overrides, the editor shows the effective discovery mode derived from either the override or the toolset default so administrators can review mixed configurations safely.

Request And Response Payload Logging

Toolsets support configurable request/response payload capture for governance purposes.

This configuration controls whether the Runtime captures and stores request and response payload data in audit records when tools from the toolset are invoked.

Configurable options include:

• whether payload logging is enabled for the toolset (disabled by default)
• the maximum payload size to capture per dimension (default 512 KB)
• per-endpoint overrides that enable or disable logging for individual tools independently of the toolset default

When enabled, captured payloads are sanitized before storage to remove sensitive values such as credentials, tokens, and secrets. Content that exceeds the configured size limit is truncated.

This feature is useful for debugging, compliance requirements, or operational review of AI-driven tool invocations, but should be enabled deliberately given the sensitivity of payload content.

Correlation Propagation

Toolsets control which correlation identifier the Runtime sends to the downstream API when a tool in the toolset is invoked, and under which header name.

Two identifiers are available: the execution ID the platform generates for the call, and the external correlation ID the caller supplied on X-Correlation-Id, when it supplied one.

Administrators choose one of five strategies:

• Execution ID — the downstream receives the platform's execution ID. This is the default.
• Caller's correlation ID only — the downstream receives the caller's value, and nothing when the caller supplied none.
• Caller's correlation ID, falling back to execution ID — the downstream always receives a header, preferring the caller's value.
• Both, on separate headers — the execution ID on the primary header and the caller's value on the secondary header.
• Do not send a correlation header — for downstream systems that reject unrecognised headers.

Both header names are configurable. The primary header defaults to X-Correlation-Id and the secondary — used only by the Both strategy — defaults to X-External-Correlation-Id. Leaving a field empty keeps the default.

A configured name must be a valid HTTP header field name. The Portal validates this both in the editor and when the configuration is saved, so a malformed header name is never persisted and can never reach an outbound request. Under Both, the two names must differ.

The effective configuration is shown in the toolset read-only view, and the setting applies to REST and SOAP tools alike.

See Runtime Downstream Invocation for how the Runtime applies the policy.

Duplicate Endpoint Exposure Warning

When creating or editing a toolset, the Portal checks whether the current configuration would result in the same endpoint being exposed to the same client application through more than one toolset.

If an overlap is detected, the Portal shows a warning banner in the toolset editor identifying the other toolsets that share both a client application and at least one endpoint. A warning icon also appears in the modal title.

The same condition is reported outside the editor, so it does not depend on someone opening the toolset to edit it: the toolset carries a warning icon in both list views, and the read-only View details modal names the overlapping toolsets in full. That modal is available to users who cannot publish, so a reviewer sees every warning a toolset carries without holding manage rights.

This check is unrelated to the tool-name rule above: overlap across separate toolsets is advisory and sometimes intentional, whereas two mappings colliding inside one toolset is refused outright.

This matters because when two toolsets expose the same endpoint to the same consumer and both governing policies pass at runtime, the AI client sees duplicate entries in tools/list, which can lead to unpredictable tool selection behavior.

The warning is advisory. Administrators can choose to proceed, for example when the governing policies on the shared endpoints are mutually exclusive by design.

Client Applications

Client applications represent consuming systems or AI clients.

Administrators can:

• create client applications
• manage client application metadata
• define an optional client application system prompt
• activate or deactivate client applications
• associate toolsets with the correct consumers

Because client application prompt changes affect runtime prompt composition, saving a client application also updates runtime configuration state and invalidates the related runtime snapshots.

Application API Keys

The Portal also supports lifecycle management for application API keys.

Functionally this includes:

• API key creation
• metadata and expiration management
• API key revocation
• API key deletion
• claim-oriented access shaping through roles, scopes, groups, and custom claims

The Tool Registry And Security Oversight

Every tool a toolset publishes is a registered identity on the platform, and the rules attached to it — its access policy and its endpoint authentication binding — hang off that identity rather than off a text label parsed at request time.

Functionally this means:

• publishing a toolset registers its tools; deselecting an endpoint deactivates the tool's row rather than deleting it, so reselecting the endpoint restores the rules that were attached to it
• a tool's rules are authored by whoever publishes the tool, using that area's own authority — an ESRA exposure manager sets the rules of the tool their exposure publishes without holding the Security area's role, and a toolset administrator does the same for theirs
• an operator can only ever see and edit the tools their own toolset or exposure publishes; enumerating a tenant's whole set is a Security oversight function, not something a publisher's screen does
• a rule can no longer be moved onto a different tool by editing a request, which previously let a caller who administered one tool write the rules of another

The Security area's Tool Oversight screen is the other half. It reads every tool in scope whoever publishes it, with the rules currently attached, and offers exactly two actions: take a tool offline, and clear a registry row whose publisher no longer exists. It authors nothing — there is no policy editor there. A quarantined tool is refused by the Runtime immediately, whatever its own policies say, and its owner cannot lift the quarantine.

Operational Importance

This area is the publication control point between internal mapping design and external runtime consumption.

It determines which AI clients can see which tools and under what application identity.