Skip to content
MCP Gateway

List canonical client surfaces visible in the requesting tenant and environment.

GET
/v1/client-surfaces

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
environment_id
required
string
>= 1 characters
lifecycle_state
string
Allowed values: submitted under_review approved rejected disabled revoked archived
client_type
string
Allowed values: hosted_agent_platform internal_agent_sdk ide_extension chat_application admin_console
owner_team
string
>= 1 characters
limit
integer
default: 50 >= 1 <= 100
cursor
string
>= 1 characters
sort
Allowed values: display_name active_session_count recent_deny_count

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Tenant and environment scoped client-surface records with metadata only.

object
schemaVersion
required
requestId
required
string
>= 1 characters
tenantId
required
string
>= 1 characters
environmentId
required
string
>= 1 characters
items
required
Array<object>
object
schemaVersion
required
clientSurfaceId
required
string
>= 1 characters
tenantId
required
string
>= 1 characters
displayName
required
string
>= 1 characters
owner
required
object
team
required
string
>= 1 characters
userId
required
string
>= 1 characters
escalationContact
required
string
>= 1 characters
oncallRotation
required
string
>= 1 characters
allowedEnvironmentIds
required
Array<string>
>= 1 items
authType
required
string
Allowed values: oidc_jwt workload_identity api_key local_identity
clientType
required
string
Allowed values: hosted_agent_platform internal_agent_sdk ide_extension chat_application admin_console
lifecycleState
required
string
Allowed values: submitted under_review approved rejected disabled revoked archived
approvalState
required
string
Allowed values: submitted under_review approved rejected disabled archived
revocationState
required
Allowed values: active disabled revoked
configSnippet
required
object
snippetId
required
string
>= 1 characters
format
required
Allowed values: mcp_json envoy_bootstrap_ref sdk_config_ref
generatedAt
required
string format: date-time
versionRef
required
string
>= 1 characters
materialReturn
required
includesSecretMaterial
required
boolean
discoverability
required
string
Allowed values: discoverable policy_filtered hidden
activeSessionCount
required
integer
recentAuditCount
required
integer
recentDenyCount
required
integer
permissions
required
object
allowedActions
required
Array
>= 1 items
Allowed values: list read use_in_policy_simulator bind_agent disable revoke view_affected_sessions
redactionStatus
required
page
required
object
limit
required
integer
>= 1 <= 100
totalCount
required
integer
nextCursor
string

400

Section titled “400 ”

Invalid cursor or list selector.

object
schemaVersion
required
requestId
required
string
>= 1 characters
status
required
integer
>= 400 <= 599
reasonCode
required
string
/^[a-z0-9_]+$/
message
required
string
>= 1 characters
retryable
required
boolean
machineSafe
required
boolean
redactionStatus
required
Allowed values: redacted metadata_only
field

Optional metadata-only field identifier for validation errors.

string
details

Optional metadata-only diagnostic details. Never include secret material, payloads, prompts, raw endpoint URLs, or customer data.

object
requiredAction
string
>= 1 characters
resourceRef
string
>= 1 characters
key
additional properties
One of:
string

403

Section titled “403 ”

Actor lacks permission to list client surfaces.

object
schemaVersion
required
requestId
required
string
>= 1 characters
status
required
integer
>= 400 <= 599
reasonCode
required
string
/^[a-z0-9_]+$/
message
required
string
>= 1 characters
retryable
required
boolean
machineSafe
required
boolean
redactionStatus
required
Allowed values: redacted metadata_only
field

Optional metadata-only field identifier for validation errors.

string
details

Optional metadata-only diagnostic details. Never include secret material, payloads, prompts, raw endpoint URLs, or customer data.

object
requiredAction
string
>= 1 characters
resourceRef
string
>= 1 characters
key
additional properties
One of:
string

Type set in Geist, Source Serif 4, and Departure Mono.