Skip to content
MCP Gateway

Read canonical client-surface metadata for simulator, agent, audit, and emergency workflows.

GET
/v1/client-surfaces/{client_surface_id}

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
client_surface_id
required
string
>= 1 characters

Query Parameters

Section titled “Query Parameters ”
environment_id
required
string
>= 1 characters

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Client-surface detail without secrets or client credentials.

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

403

Section titled “403 ”

Actor lacks permission to read this client surface.

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

404

Section titled “404 ”

Surface is absent or outside the caller tenant/environment scope.

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.