CustomMCPServer
A project-scoped, HTTP-only MCP server definition, keyed (tenant_id, project_id, server_id). Its wire ID is "custom:{server_id}".
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.
Usage profiles
| Usage | Fields and validation |
|---|---|
| In requests | View fields |
| In responses | View fields |
In requests
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
serverId | string | Required in requests | Unique within the project. Pattern: ^[a-z0-9][a-z0-9-]{0,62}$. |
displayName | string | Optional | Display name used for the registered MCP server. Maximum length: 200. |
description | string | Optional | Human-readable description of the resource. Maximum length: 1024. |
endpoint | 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://. |
authType | 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) (1, 2, 3, 4) | Optional | Authentication mechanism configured for the MCP server. |
authSecretRef | 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. |
authHeaderName | 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})?$. |
enabled | boolean | Optional | Whether this configuration is enabled. |
requestTimeout | 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$. |
version | string (int64) | Optional | Output-only revision assigned by the store and incremented on updates. Ignored on writes. Pattern: ^-?\d+$. |
createdBy | string | Optional | Output-only identity of the caller that registered the server. Ignored on writes. |
createdAt | string (date-time) | Optional | Output-only creation time assigned by the store. Ignored on writes. |
updatedAt | string (date-time) | Optional | Output-only last-update time assigned by the store. Ignored on writes. |
authQueryParam | string | Optional | Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey"). Empty is allowed — populated only for QUERY auth. Pattern: ^([A-Za-z0-9._~-]{1,128})?$. |
Values of authType
How credentials are attached to requests to a tenant-configured MCP server.
| Value | No. | Form | Meaning |
|---|---|---|---|
CUSTOM_MCP_SERVER_AUTH_TYPE_NONE | 1 | Canonical | Send requests without attaching a secret for authentication. |
CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER | 2 | Canonical | Send the secret as a Bearer token in the Authorization header. |
CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER | 3 | Canonical | Send the secret in the configured custom header. |
CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY | 4 | Canonical | Add the secret as the configured URL query parameter when connecting; the stored endpoint remains the base URL. |
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!#$%&'*+.^_|~-]128)?$` |
requestTimeout | At most | 120s |
authQueryParam | Pattern | ^([A-Za-z0-9._~-]{1,128})?$ |
In responses
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
serverId | string | Required in requests | Unique within the project. |
displayName | string | Optional | Display name used for the registered MCP server. |
description | string | Optional | Human-readable description of the resource. |
endpoint | 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. |
authType | 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 | Authentication mechanism configured for the MCP server. |
authSecretRef | 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. |
authHeaderName | 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. |
enabled | boolean | Optional | Whether this configuration is enabled. |
requestTimeout | 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$. |
version | string (int64) | Optional | Output-only revision assigned by the store and incremented on updates. Ignored on writes. Pattern: ^-?\d+$. |
createdBy | string | Optional | Output-only identity of the caller that registered the server. Ignored on writes. |
createdAt | string (date-time) | Optional | Output-only creation time assigned by the store. Ignored on writes. |
updatedAt | string (date-time) | Optional | Output-only last-update time assigned by the store. Ignored on writes. |
authQueryParam | string | Optional | Required for QUERY auth; the vendor's parameter name (e.g. "tavilyApiKey"). Empty is allowed — populated only for QUERY auth. |
Values of authType
How credentials are attached to requests to a tenant-configured MCP server.
| Value | No. | Form | Meaning |
|---|---|---|---|
CUSTOM_MCP_SERVER_AUTH_TYPE_NONE | 1 | Canonical | Send requests without attaching a secret for authentication. |
CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER | 2 | Canonical | Send the secret as a Bearer token in the Authorization header. |
CUSTOM_MCP_SERVER_AUTH_TYPE_HEADER | 3 | Canonical | Send the secret in the configured custom header. |
CUSTOM_MCP_SERVER_AUTH_TYPE_QUERY | 4 | Canonical | Add the secret as the configured URL query parameter when connecting; the stored endpoint remains the base URL. |
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!#$%&'*+.^_|~-]128)?$` |
requestTimeout | At most | 120s |
authQueryParam | Pattern | ^([A-Za-z0-9._~-]{1,128})?$ |
Where used
| Reference | Relationship |
|---|---|
| Register a custom MCP server | POST /api/v1/mcp-servers/create |
| Update a custom MCP server | POST /api/v1/mcp-servers/update |
| Get a custom MCP server | POST /api/v1/mcp-servers/get |
| List custom MCP servers | POST /api/v1/mcp-servers/list |
Download the public reference contract.
Document: DOC-API-MODEL-custom-mcp-server.