MCP Gateway API: schemas

The request and response bodies of the operations in this API.

AddCatalogEntryBiomeToolDto

Property	Type	Required	Description
`biomeInstallationId`	string	yes	Biome installation that owns the tool.
`biomeToolKey`	string	yes	Tool key from the authoritative workflow contribution. NOT the projected `<biomeId>__<key>` form.
`kind`	CatalogEntryRequestKind	yes	Discriminator. `biome_workflow_tools` — a workflow-backed biome tool.

AddCatalogEntryMcpServerDto

Property	Type	Required	Description
`discoveredToolId`	string (uuid)	yes	ID of the discovered tool to add.
`kind`	CatalogEntryRequestKind	yes

AddToolToCatalogDto

Property	Type	Required	Description
`entry`	AddCatalogEntryMcpServerDto or AddCatalogEntryBiomeToolDto	yes

AdmitToolDto

Property	Type	Required	Description
`expectedDefinitionHash`	string	yes	The definitionHash the admin reviewed. Admission is refused with 409 if the tool definition has changed since.

CapabilityRoleBindingResponseDto

Property	Type	Required	Description
`concreteCapabilityRef`	string	yes	Concrete capability ref the role resolves to.
`createdAt`	string (date-time)	yes
`id`	string	yes
`orgId`	string	yes
`role`	string	yes	Abstract logical role name.
`updatedAt`	string (date-time)	yes

CapabilityRoleBindingResponseDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of CapabilityRoleBindingResponseDto	yes

CapabilityRoleBindingResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	CapabilityRoleBindingResponseDto	yes

CatalogEntryRequestKind

Type: one of "mcp_server", "biome_workflow_tools"

CatalogResponseDto

Property	Type	Required	Description
`_count`	object	no	Number of tools in this catalog.
`createdAt`	string (date-time)	yes
`description`	string	yes
`id`	string	yes
`isDefault`	boolean	yes
`name`	string	yes
`orgId`	string	yes
`updatedAt`	string (date-time)	yes
`version`	number	yes

CatalogResponseDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of CatalogResponseDto	yes

CatalogResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	CatalogResponseDto	yes

CreateCatalogDto

Property	Type	Required	Description
`description`	string	yes	Catalog description.
`isDefault`	boolean	no	Whether this is the default catalog.
`name`	string	yes	Catalog name.

DiscoveredToolResponseDto

Property	Type	Required	Description
`admittedDefinitionHash`	string or null	no	Hash of the definition an admin admitted. Absent: never admitted.
`annotations`	object or null	no	MCP tool annotations as the upstream sent them.
`canonicalName`	string	yes
`createdAt`	string (date-time)	yes
`definitionHash`	string or null	no	Hash of the tool definition as last discovered. Send it to the admit route.
`description`	string	yes
`displayName`	string	yes
`enabledByAdmin`	boolean	yes
`id`	string	yes
`inputSchema`	object or null	no
`orgMcpServerId`	string	yes
`outputSchema`	object or null	no	JSON Schema of the tool result, when the upstream declares one.
`requiredCapabilities`	array of string	yes	CapabilityRef strings this tool needs (per-tool, or inherited from the catalog service default). The agent auto-grant engine unions these across an agent's armed tools. Empty ⇒ no declared capabilities.
`status`	one of `"active"`, `"retired"`, `"disabled"`, `"awaiting_admission"`	yes
`toolGroup`	string or null	no
`updatedAt`	string (date-time)	yes
`version`	number	yes

DiscoveredToolResponseDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of DiscoveredToolResponseDto	yes

DiscoveredToolResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	DiscoveredToolResponseDto	yes

McpDiscoveryCatalogServerDto

Property	Type	Required
`availability`	one of `"attachable"`, `"inactive"`	yes
`contributedToolCount`	number	yes
`displayName`	string	yes
`id`	string	yes
`readinessState`	string (11 values)	yes
`serviceKey`	string	yes

McpDiscoveryCatalogSnapshotDto

Property	Type	Required	Description
`availability`	one of `"attachable"`, `"inactive"`	yes	Aggregate readiness rolled up from contributing servers. `attachable` iff every contributing server is `ready` for the requested intent.
`connectionUrl`	string	yes	URL the worker connects to (`{gateway}/mcp/catalog/{catalogId}`).
`contributingServers`	array of McpDiscoveryCatalogServerDto	yes
`description`	string	yes
`id`	string	yes
`isDefault`	boolean	yes
`name`	string	yes
`orgId`	string	yes
`readinessState`	string (11 values)	yes
`toolCount`	number	yes
`version`	number	yes

McpDiscoveryCatalogSnapshotDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of McpDiscoveryCatalogSnapshotDto	yes

McpDiscoveryInventoryResponseDto

Property	Type	Required
`activeToolCount`	number	yes
`authType`	one of `"none"`, `"bearer"`, `"api_key"`, `"basic"`, `"oauth2"`, `"oauth2_auth_code"`	no
`availability`	one of `"attachable"`, `"inactive"`	yes
`catalogIsDefault`	boolean	no
`catalogVersion`	number	no
`connectionUrl`	string	yes
`contributingServerCount`	number	no
`description`	string	yes
`displayName`	string	yes
`healthStatus`	string	no
`id`	string	yes
`isVirtual`	boolean	yes
`kind`	one of `"server"`, `"catalog"`	yes
`orgId`	string	no
`ownershipType`	one of `"system"`, `"org"`	no
`readinessState`	string (11 values)	yes
`serverType`	one of `"native_mcp"`, `"openapi_bridge"`	no
`serviceKey`	string	yes
`specAuthType`	one of `"none"`, `"bearer"`, `"api_key"`, `"basic"`, `"oauth2"`, `"oauth2_auth_code"`	no
`toolCount`	number	yes
`toolGroups`	array of string	yes

McpDiscoveryInventoryResponseDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of McpDiscoveryInventoryResponseDto	yes

McpDiscoveryServerResponseDto

Property	Type	Required
`activeToolCount`	number	yes
`authType`	one of `"none"`, `"bearer"`, `"api_key"`, `"basic"`, `"oauth2"`, `"oauth2_auth_code"`	yes
`availability`	one of `"attachable"`, `"inactive"`	yes
`connectionUrl`	object or null	no
`description`	string	yes
`displayName`	string	yes
`healthStatus`	string	yes
`id`	string	yes
`isActive`	boolean	yes
`openapiSpecUrl`	object or null	no
`orgId`	object or null	no
`ownershipType`	one of `"system"`, `"org"`	yes
`readinessState`	string (11 values)	yes
`serverType`	one of `"native_mcp"`, `"openapi_bridge"`	yes
`serviceKey`	string	yes
`specAuthType`	one of `"none"`, `"bearer"`, `"api_key"`, `"basic"`, `"oauth2"`, `"oauth2_auth_code"`	yes
`toolCount`	number	yes
`toolGroups`	array of string	yes

McpDiscoveryServerResponseDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of McpDiscoveryServerResponseDto	yes

McpServerResponseDto

Property	Type	Required	Description
`apiBaseUrl`	string or null	no	Upstream API base URL for openapi_bridge servers. Populated from `spec.servers[0].url` during tool discovery.
`authType`	one of `"none"`, `"bearer"`, `"api_key"`, `"basic"`, `"oauth2"`, `"oauth2_auth_code"`	yes
`connectionUrl`	string or null	no
`createdAt`	string (date-time)	yes
`description`	string	yes
`displayName`	string	yes
`healthStatus`	string	yes
`id`	string	yes
`isActive`	boolean	yes
`lastHealthCheck`	string (date-time) or null	no
`openapiSpecUrl`	string or null	no
`orgId`	string or null	no
`ownershipType`	one of `"system"`, `"org"`	yes
`serverType`	one of `"native_mcp"`, `"openapi_bridge"`	yes
`serviceKey`	string	yes
`source`	one of `"official_registry"`, `"manual"`	yes	Registration provenance — `official_registry` (curated) or `manual` (user-supplied).
`specAuthType`	one of `"none"`, `"bearer"`, `"api_key"`, `"basic"`, `"oauth2"`, `"oauth2_auth_code"`	yes
`toolCount`	number	yes
`updatedAt`	string (date-time)	yes
`version`	number	yes

McpServerResponseDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of McpServerResponseDto	yes

McpServerResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	McpServerResponseDto	yes

OAuthInitiateRequestDto

Property	Type	Required	Description
`redirectUri`	string (uri)	yes	The redirect URI the authorization server will redirect to after user consent. Must match the URI registered with the authorization server.

OAuthInitiateResponseDto

Property	Type	Required	Description
`consentUrl`	string	yes	Authorization URL to redirect the user to for consent. The caller must open this URL in a browser.
`state`	string	yes	CSRF-proof state parameter. The caller should store it and verify it matches the `state` returned by the callback.

OAuthInitiateResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	OAuthInitiateResponseDto	yes

ObjectDataEnvelope

Property	Type	Required	Description
`data`	object	yes

ProblemActionableBy

Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed.

Type: one of "user", "org-admin", "platform", "none"

ProblemDetailsDto

RFC 9457 problem document. The declared members are the reserved core; extension members are TOP-LEVEL and OPEN, owned by the refusing plane.

Property	Type	Required	Description
`actionableBy`	ProblemActionableBy	no	Who can act on this refusal: `user` (correct the input, sign in), `org-admin` (an administrator of the organisation), `platform` (the operators of this installation), `none` (nobody — it cannot succeed). ABSENT when not known; never guessed.
`code`	string	yes	SCREAMING_SNAKE_CASE. The machine-branchable refusal, and the value a policy rule, a retry predicate and a UI branch all name.
`detail`	string	no	Human-readable and specific to THIS occurrence.
`errors`	array of ProblemFieldIssueDto	no	Field-level issues, when the refusal is about the request body.
`instance`	string	no	URI reference identifying the occurrence — a request path, a run, a row.
`params`	map of string or number or boolean	no	Safe i18n interpolation values for the message keyed by `code` — typed and allowlisted per code by its declaration. Never server-authored copy, never internal diagnostics.
`retry`	ProblemRetry	no	What a retry can achieve: `transient` (later, unchanged), `after-change` (only after someone changes something), `never` (a defect until a fixed version ships). ABSENT when not known.
`status`	number	yes	The HTTP status code, repeated in the body so a logged document is self-contained.
`title`	string	yes	Short, human-readable, and STABLE for a given `type`. Never per-occurrence — that is `detail`.
`traceId`	string	no	W3C trace-context trace-id, present when the caller sent a `traceparent`. Omitted rather than invented when it did not.
`type`	string	yes	Absolute URI identifying the refusal TYPE. Derived one-to-one from `code`, so a caller may branch on either and can never be told two different things. Never `about:blank`.

ProblemFieldIssueDto

Property	Type	Required	Description
`code`	string	no	SCREAMING_SNAKE_CASE code of THIS issue, for a frontend i18n key. Present when the issue was minted by a declared problem.
`detail`	string	yes	Prose for logs and developers. A frontend localises from `code` + `params` instead.
`params`	map of string or number or boolean	no	Safe i18n interpolation values for this issue's `code`.
`pointer`	string	yes	RFC 6901 JSON Pointer into the request body. Root is "/".

ProblemRetry

What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known.

Type: one of "transient", "after-change", "never"

RegisterServerDto

Property	Type	Required	Description
`authConfig`	object	no	Auth configuration for invoking this server. STORED AS PLAINTEXT JSON today — this field said "encrypted at rest" and no encryption existed. The credential-broker binding on the server row is the source of truth for invocation credentials; this column is retired by the MCP-as-Connector phase. Do not add a field here that carries secret material.
`authType`	one of `"none"`, `"bearer"`, `"api_key"`, `"basic"`, `"oauth2"`, `"oauth2_auth_code"`	yes	Authentication type.
`connectionUrl`	string (uri)	no	MCP server endpoint URL (for native_mcp).
`description`	string	yes	Description for LLM context.
`displayName`	string	yes	Display name for the server.
`openapiSpecRaw`	string	no	Inline OpenAPI spec JSON (for openapi_bridge).
`openapiSpecUrl`	string (uri)	no	OpenAPI spec URL (for openapi_bridge).
`ownershipType`	one of `"system"`, `"org"`	yes	Server ownership type.
`serverType`	one of `"native_mcp"`, `"openapi_bridge"`	yes	Server type.
`serviceKey`	string	yes	Unique service key within scope.
`source`	one of `"official_registry"`, `"manual"`	no	Provenance of the registration — `official_registry` (curated MCP registry catalogue) or `manual` (user-supplied endpoint). Defaults to `manual`, the harder-gated path.
`specAuthConfig`	object	no	Auth configuration used only to fetch a protected OpenAPI spec.
`specAuthType`	one of `"none"`, `"bearer"`, `"api_key"`, `"basic"`, `"oauth2"`, `"oauth2_auth_code"`	no	Authentication type used only to fetch a protected OpenAPI spec.

ResolvedCapabilityRoleResponseDto

Property	Type	Required	Description
`concreteCapabilityRef`	string	yes	The concrete capability ref the role resolves to.
`role`	string	yes	The role that was resolved.

ResolvedCapabilityRoleResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	ResolvedCapabilityRoleResponseDto	yes

TestConnectivityResponseDto

Property	Type	Required
`connectivityError`	string or null	no
`latencyMs`	number or null	no
`reachable`	boolean	yes
`toolCount`	number or null	no

TestConnectivityResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	TestConnectivityResponseDto	yes

UpdateCatalogDto

Property	Type	Required	Description
`description`	string	no	Updated catalog description.
`expectedVersion`	number	yes	Expected current version for optimistic concurrency.
`isDefault`	boolean	no	Whether this is the default catalog.
`name`	string	no	Updated catalog name.

UpdateServerDto

Property	Type	Required	Description
`authConfig`	object	no	Updated auth configuration.
`authType`	one of `"none"`, `"bearer"`, `"api_key"`, `"basic"`, `"oauth2"`, `"oauth2_auth_code"`	no	Updated auth type.
`connectionUrl`	string (uri)	no	Updated MCP server endpoint URL.
`description`	string	no	Updated description.
`displayName`	string	no	Updated display name.
`expectedVersion`	number	yes	Expected current version for optimistic concurrency.
`isActive`	boolean	no	Enable or disable the server.
`openapiSpecRaw`	string	no	Updated inline OpenAPI spec JSON.
`openapiSpecUrl`	string (uri)	no	Updated OpenAPI spec URL.
`specAuthConfig`	object	no	Updated OpenAPI spec auth configuration.
`specAuthType`	one of `"none"`, `"bearer"`, `"api_key"`, `"basic"`, `"oauth2"`, `"oauth2_auth_code"`	no	Updated auth type used only to fetch a protected OpenAPI spec.

UpsertCapabilityRoleBindingDto

Property	Type	Required	Description
`concreteCapabilityRef`	string	yes	Concrete capability ref that fulfils the role, e.g. `<provider-slug>:<tool-name>@1`.
`role`	string	yes	Abstract logical role name the org defines (e.g. `mail.send`). Opaque to the service.