DOC-API-MODEL-schema-p1cuh9jgfq#overview
CustomMCPServer
A project-scoped, HTTP-only MCP server definition, keyed (tenant_id, project_id, server_id). Its wire ID is "custom:{server_id}".
Credentials must be stored as secret references; inline tokens must not be persisted in this server definition.
auth_type selects the required credential fields. Authenticated modes require auth_secret_ref; NONE requires it to be empty. HEADER requires auth_header_name and QUERY requires auth_query_param; those names must be empty for every other mode. Inconsistent combinations are rejected before storage. Inline credentials are not accepted.
Input constraints
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#input-constraints
server_id
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#server_id
The server_id must contain one through 63 characters. Its first character must be a lowercase ASCII letter or digit. Every remaining character must be a lowercase ASCII letter, digit, or hyphen.
auth_header_name
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#auth_header_name
The auth_header_name may be empty text. Otherwise it must contain one through 128 characters, each an ASCII letter, digit, or one of these literal punctuation characters: ! # $ % & ' * + . ^ _ ` | ~ -. No other character is accepted.
auth_query_param
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#auth_query_param
The auth_query_param may be empty text. Otherwise it must contain one through 128 characters, each an ASCII letter, digit, period, underscore, tilde, or hyphen. No other character is accepted.
request_timeout
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#request_timeout
The request_timeout duration must be no greater than 120 seconds.
Meaning and usage
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#meaning
See the definition above.
Input constraints
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#input-constraints-1
See the definition above.
server_id
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#server_id-1
See the definition above.
auth_header_name
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#auth_header_name-1
See the definition above.
auth_query_param
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#auth_query_param-1
See the definition above.
request_timeout
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#request_timeout-1
See the definition above.
Usage profiles
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#fields
| Usage | Fields and validation |
|---|---|
| In requests | View fields |
| In responses | View fields |
In requests
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#request
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#request-field-serveridserverId | string | Required in requests | Unique within the project. Pattern: ^[a-z0-9][a-z0-9-]{0,62}$. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#request-field-displaynamedisplayName | string | Optional | Display name used for the registered MCP server. Maximum length: 200. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#request-field-descriptiondescription | string | Optional | Human-readable description of the resource. Maximum length: 1024. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#request-field-endpointendpoint | string (uri) | Required in requests | HTTPS endpoint for Streamable HTTP; local and standard-input/output transports are unsupported. The egress guard also rejects prohibited destinations such as metadata, loopback, private-network and in-cluster addresses. HTTPS alone does not satisfy these destination checks. Maximum length: 2048. Pattern: ^https://. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#request-field-authtypeauthType | string (CUSTOM_MCP_SERVER_AUTH_TYPE_NONE, CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER, CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER, CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY) or integer (int32) (0, 1, 2, 3) | Optional; explicit presence | Authentication mechanism configured for the MCP server. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#request-field-authsecretrefauthSecretRef | SecretRef | Optional | Required credential reference for BEARER, HEADER and QUERY authentication. Resolves within this server's tenant and project; only the secret name is returned, never its value. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#request-field-authheadernameauthHeaderName | string | Optional | Name of the custom authentication header. The egress guard also rejects protected header names; satisfying the field's character pattern alone does not permit every header. Pattern: ^([A-Za-z0-9!#$%&'*+.^_`|~-]{1,128})?$. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#request-field-authqueryparamauthQueryParam | string | Optional | See meaning below. Pattern: ^([A-Za-z0-9._~-]{1,128})?$. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#request-field-enabledenabled | boolean | Optional | Whether this configuration is enabled. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#request-field-requesttimeoutrequestTimeout | string | Optional | Time allowed for a remote request. Omission or a nonpositive duration uses 30 seconds; positive durations below one second are raised to one second. Long waits can delay the conversation while the remote server is unavailable. Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#request-field-versionversion | string (int64) | Optional | Output-only revision assigned by the store and incremented on updates. Ignored on writes. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#request-field-createdbycreatedBy | string | Optional | Output-only identity of the caller that registered the server. Ignored on writes. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#request-field-createdatcreatedAt | string (date-time) | Optional | Output-only creation time assigned by the store. Ignored on writes. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#request-field-updatedatupdatedAt | string (date-time) | Optional | Output-only last-update time assigned by the store. Ignored on writes. |
authQueryParam
Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey").
Restricted to RFC 3986 unreserved characters, which is NOT the same set as auth_header_name's RFC 7230 tchar: that set contains '&' (would append a second parameter), '#' (would truncate the URL at a fragment), '%' (would open a malformed escape) and '+' (decodes as a space). The query-parameter name uses its own character set.
Empty is allowed — populated only for QUERY auth.
Values of authType
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#request-values-authtype
How credentials are attached to requests to a tenant-configured MCP server. Credentials are held by reference; inline credential values are neither accepted nor persisted.
| Value | No. | Form | Meaning |
|---|---|---|---|
CUSTOM_MCP_SERVER_AUTH_TYPE_NONE | 0 | Canonical | Send requests without attaching a secret for authentication. |
CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER | 1 | Canonical | See meaning below. |
CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER | 2 | Canonical | See meaning below. |
CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY | 3 | Canonical | See meaning below. |
CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER
Send the secret as a Bearer token in the Authorization header.
Authorization: Bearer <secret>
CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER
Send the secret in the configured custom header.
<auth_header_name>: <secret>
CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY
Add the secret as the configured URL query parameter when connecting; the stored endpoint remains the base URL.
<endpoint>?<auth_query_param>=<secret>. The secret is joined to the URL at dial time only — the endpoint column and the cache payload keep the bare URL. Exists because some vendors (Tavily) document no header alternative.
Request validation
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#request-validation
These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules.
| Applies to | Rule | Requirement |
|---|---|---|
serverId | Pattern | ^[a-z0-9][a-z0-9-]{0,62}$ |
displayName | Maximum length | 200 |
description | Maximum length | 1024 |
endpoint | Maximum length | 2048 |
endpoint | Pattern | ^https:// |
endpoint | Uri | true |
authType | Defined enum value | true |
authHeaderName | Pattern | ^([A-Za-z0-9!#$%&'*+.^_`|~-]{1,128})?$ |
authQueryParam | Pattern | ^([A-Za-z0-9._~-]{1,128})?$ |
requestTimeout | At most | 120s |
In responses
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#response
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#field-serveridSection ID: DOC-API-MODEL-schema-p1cuh9jgfq#response-field-serveridserverId | string | Required in requests | Unique within the project. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#field-displaynameSection ID: DOC-API-MODEL-schema-p1cuh9jgfq#response-field-displaynamedisplayName | string | Optional | Display name used for the registered MCP server. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#field-descriptionSection ID: DOC-API-MODEL-schema-p1cuh9jgfq#response-field-descriptiondescription | string | Optional | Human-readable description of the resource. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#field-endpointSection ID: DOC-API-MODEL-schema-p1cuh9jgfq#response-field-endpointendpoint | string | Required in requests | HTTPS endpoint for Streamable HTTP; local and standard-input/output transports are unsupported. The egress guard also rejects prohibited destinations such as metadata, loopback, private-network and in-cluster addresses. HTTPS alone does not satisfy these destination checks. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#field-authtypeSection ID: DOC-API-MODEL-schema-p1cuh9jgfq#response-field-authtypeauthType | string (CUSTOM_MCP_SERVER_AUTH_TYPE_NONE, CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER, CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER, CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY) or integer (int32) | Optional; explicit presence | Authentication mechanism configured for the MCP server. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#field-authsecretrefSection ID: DOC-API-MODEL-schema-p1cuh9jgfq#response-field-authsecretrefauthSecretRef | SecretRef | Optional | Required credential reference for BEARER, HEADER and QUERY authentication. Resolves within this server's tenant and project; only the secret name is returned, never its value. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#field-authheadernameSection ID: DOC-API-MODEL-schema-p1cuh9jgfq#response-field-authheadernameauthHeaderName | string | Optional | Name of the custom authentication header. The egress guard also rejects protected header names; satisfying the field's character pattern alone does not permit every header. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#field-authqueryparamSection ID: DOC-API-MODEL-schema-p1cuh9jgfq#response-field-authqueryparamauthQueryParam | string | Optional | See meaning below. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#field-enabledSection ID: DOC-API-MODEL-schema-p1cuh9jgfq#response-field-enabledenabled | boolean | Optional | Whether this configuration is enabled. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#field-requesttimeoutSection ID: DOC-API-MODEL-schema-p1cuh9jgfq#response-field-requesttimeoutrequestTimeout | string | Optional | Time allowed for a remote request. Omission or a nonpositive duration uses 30 seconds; positive durations below one second are raised to one second. Long waits can delay the conversation while the remote server is unavailable. Pattern: ^-?(?:0|[1-9][0-9]*)(?:\.[0-9]{1,9})?s$. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#field-versionSection ID: DOC-API-MODEL-schema-p1cuh9jgfq#response-field-versionversion | string (int64) | Optional | Output-only revision assigned by the store and incremented on updates. Ignored on writes. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#field-createdbySection ID: DOC-API-MODEL-schema-p1cuh9jgfq#response-field-createdbycreatedBy | string | Optional | Output-only identity of the caller that registered the server. Ignored on writes. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#field-createdatSection ID: DOC-API-MODEL-schema-p1cuh9jgfq#response-field-createdatcreatedAt | string (date-time) | Optional | Output-only creation time assigned by the store. Ignored on writes. |
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#field-updatedatSection ID: DOC-API-MODEL-schema-p1cuh9jgfq#response-field-updatedatupdatedAt | string (date-time) | Optional | Output-only last-update time assigned by the store. Ignored on writes. |
authQueryParam
Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey").
Restricted to RFC 3986 unreserved characters, which is NOT the same set as auth_header_name's RFC 7230 tchar: that set contains '&' (would append a second parameter), '#' (would truncate the URL at a fragment), '%' (would open a malformed escape) and '+' (decodes as a space). The query-parameter name uses its own character set.
Empty is allowed — populated only for QUERY auth.
Values of authType
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#response-values-authtype
How credentials are attached to requests to a tenant-configured MCP server. Credentials are held by reference; inline credential values are neither accepted nor persisted.
| Value | No. | Form | Meaning |
|---|---|---|---|
CUSTOM_MCP_SERVER_AUTH_TYPE_NONE | 0 | Canonical | Send requests without attaching a secret for authentication. |
CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER | 1 | Canonical | See meaning below. |
CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER | 2 | Canonical | See meaning below. |
CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY | 3 | Canonical | See meaning below. |
CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER
Send the secret as a Bearer token in the Authorization header.
Authorization: Bearer <secret>
CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER
Send the secret in the configured custom header.
<auth_header_name>: <secret>
CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY
Add the secret as the configured URL query parameter when connecting; the stored endpoint remains the base URL.
<endpoint>?<auth_query_param>=<secret>. The secret is joined to the URL at dial time only — the endpoint column and the cache payload keep the bare URL. Exists because some vendors (Tavily) document no header alternative.
DOC-API-MODEL-schema-p1cuh9jgfq#validation
Request validation
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#response-validation
These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules.
| Applies to | Rule | Requirement |
|---|---|---|
serverId | Pattern | ^[a-z0-9][a-z0-9-]{0,62}$ |
displayName | Maximum length | 200 |
description | Maximum length | 1024 |
endpoint | Maximum length | 2048 |
endpoint | Pattern | ^https:// |
endpoint | Uri | true |
authType | Defined enum value | true |
authHeaderName | Pattern | ^([A-Za-z0-9!#$%&'*+.^_`|~-]{1,128})?$ |
authQueryParam | Pattern | ^([A-Za-z0-9._~-]{1,128})?$ |
requestTimeout | At most | 120s |
Where used
Section ID: DOC-API-MODEL-schema-p1cuh9jgfq#where-used
| Reference | Relationship |
|---|---|
| Register a custom MCP server | POST /api/v1/mcp-servers/create |
| Get a custom MCP server | POST /api/v1/mcp-servers/get |
| List custom MCP servers | POST /api/v1/mcp-servers/list |
| Update a custom MCP server | POST /api/v1/mcp-servers/update |
Download the public reference contract.
Document ID: DOC-API-MODEL-schema-p1cuh9jgfq