Skip to content
Kindgi

List MCP endpoints

View as Markdown
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>'

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

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 25 >= 1 <= 100

1..100. Default 25.

cursor
string

Where the previous page ended: its nextCursor, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise 400 bad-input, and the list starts again without it. 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

Section titled “Responses”

200

Section titled “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
transport
required
Allowed value: stdio
command
required
string
>= 1 characters
args
Array<string>
env
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 by the runtime (the shape webhooks and providers use). As the endpoint’s own secretRef, it is sent as its bearer; inside auth, it is the scheme’s password, client secret or header value. The endpoint keeps only this reference.

object
envName
required
string
/^[a-z][a-z0-9-]{0,62}$/
name
required
string
>= 1 characters <= 256 characters
auth
One of: discriminator: scheme

HTTP Basic: the runtime sends Authorization: Basic base64(<username>:<secret>), with the secret secretRef names (a WordPress Application Password, for one).

object
scheme
required
Allowed value: basic
username
required

The user name. Not a secret, and without :.

string
>= 1 characters <= 256 characters /^[^:]+$/
secretRef
required

The secret an MCP endpoint authenticates with: a name in the deployment’s secrets store, resolved at the endpoint’s tenant scope by the runtime (the shape webhooks and providers use). As the endpoint’s own secretRef, it is sent as its bearer; inside auth, it is the scheme’s password, client secret or header value. 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
sendTraceparent

Send the W3C traceparent of the run calling a tool to this endpoint, as a request header, so the server’s logs can be matched to the run. Ids only, never content. Default false. HTTP transports only: true on a stdio endpoint is refused (invalid-mcp-endpoint, reason invalid-send-traceparent). An older runtime ignores it and sends none.

boolean
secretScopes

Where each secret it names is read, by name: recorded by the server when it was registered, never sent by a caller. null: none usable (the registrant administers no scope the secret could be read at), until an admin records it again: a tool by publishing a new version, an MCP endpoint by unregistering it and registering it again. Absent on items registered before it was recorded, or on a runtime without a secrets store.

object
key
additional properties
One of:
One of:
object
kind
required
string
Allowed value: tenant
nextCursor
string
hasMore
required
boolean
Example
{
  "data": [
    {
      "transport": "stdio",
      "config": {
        "transport": "stdio"
      },
      "auth": {
        "scheme": "basic"
      },
      "secretScopes": {
        "additionalProperty": {
          "kind": "tenant"
        }
      }
    }
  ]
}

400

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also