List MCP endpoints

GET

/v1/mcp/endpoints

curl --request GET \
  --url 'https://example.com/v1/mcp/endpoints?limit=25&transport=stdio&scopeKind=tenant&inherit=true' \
  --header 'Authorization: Bearer <token>'

• Same-origin — path relative to the deployment root.

Cursor-paginated. Optional ?transport= narrows to a single variant (stdio | http-sse | streamable-http). ?scopeKind + ?scopeId + ?inherit narrow to a specific scope; inherit is LOAD-BEARING here (policy/config-scoped binding — controls the upward-hierarchy walk).

Authorizations

• bearerAuth

Parameters

Query Parameters

limit

integer

default: 25 >= 1 <= 100

1..100. Default 25.

cursor

string

Opaque cursor from a prior response. Absent → first page.

transport

MCP transport variant. stdio — local subprocess (spawn a command). http-sse — the older MCP HTTP+SSE transport (separate POST + SSE endpoints). streamable-http — the Streamable HTTP transport (single endpoint, session id via header).

string

Allowed values: stdio http-sse streamable-http

Filter to endpoints of a single transport variant. Values: stdio | http-sse | streamable-http.

scopeKind

Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId.

string

Allowed values: tenant org project

Optional scope discriminator. If absent, no scope filter is applied.

scopeId

string

>= 1 characters

Required IF scopeKind is org or project. MUST be absent if scopeKind=tenant (tenant is implicit from the session). Malformed combinations return 400 scope-invalid.

inherit

boolean

default: true

Default true. false = literal-at-this-scope only (admin/audit view). Load-bearing for policy/config-scoped resources (mcp-endpoints); documented no-op for content-scoped resources (agents/flows/tools/…).

Responses

200

Page of MCP endpoints.

Media typeapplication/json

object

data

required

Array<object>

object

endpointId

required

string

>= 1 characters

name

required

Human-readable display name.

string

>= 1 characters

transport

required

MCP transport variant. stdio — local subprocess (spawn a command). http-sse — the older MCP HTTP+SSE transport (separate POST + SSE endpoints). streamable-http — the Streamable HTTP transport (single endpoint, session id via header).

string

Allowed values: stdio http-sse streamable-http

config

required

One of:

object

object

transport

required

Allowed value: stdio

command

required

string

>= 1 characters

args

Array<string>

env

object

key

additional properties

string

object

object

transport

required

Allowed value: http-sse

url

required

string format: uri

sseUrl

Optional distinct SSE endpoint if the server splits them.

string format: uri

headers

object

key

additional properties

string

object

object

transport

required

Allowed value: streamable-http

url

required

string format: uri

headers

object

key

additional properties

string

secretRef

The secret an MCP endpoint authenticates with: a name in the deployment’s secrets store, resolved at the endpoint’s tenant scope when the runtime connects (the shape webhooks and providers use). It is sent as the endpoint’s bearer. The endpoint keeps only this reference.

object

envName

required

string

/^[a-z][a-z0-9-]{0,62}$/

name

required

string

>= 1 characters <= 256 characters

instructions

Optional pass-through to the MCP client serverInfo.instructions.

string

metadata

Optional caller-defined metadata bag.

object

key

additional properties

any

nextCursor

string

hasMore

required

boolean

Example

{
  "data": [
    {
      "transport": "stdio",
      "config": {
        "transport": "stdio"
      }
    }
  ]
}

400

Malformed query parameter.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}