# List MCP endpoints

GET

/v1/mcp/endpoints

```sh
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

- **[bearerAuth](https://docs.kindgi.com/v0.1.10/reference/api.md#bearerauth)**

## Parameters

### 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

### 200

Page of MCP endpoints.

application/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**

  Headers sent with every request, as given. Not for a credential: a header named `Authorization`, `Proxy-Authorization` or `Cookie`, or with a `-`/`_`-separated part `token`, `secret`, `password`, `passwd`, `apikey`, `credential`, `credentials`, `signature`, `session`, `auth`, `authorization` or `authentication`, or the parts `api-key`, `access-key`, `private-key`, `auth-key`, `subscription-key`, `functions-key`, `application-key`, `app-key`, `master-key`, `client-key` or `partner-key` (`X-Api-Key`, `X-Auth-Token`), is refused (`invalid-mcp-endpoint`, reason `credential-in-headers`). Send it by reference: `auth` with `scheme: header`, or `secretRef` for a bearer. An endpoint registered with one before keeps working, and its value reads back as `[redacted]`.

  object

  **_key_**

  additional properties

  string

- **object**

  object

  **transport**

  required

  Allowed value: streamable-http

  **url**

  required

  string format: uri

  **headers**

  Headers sent with every request, as given. Not for a credential: a header named `Authorization`, `Proxy-Authorization` or `Cookie`, or with a `-`/`_`-separated part `token`, `secret`, `password`, `passwd`, `apikey`, `credential`, `credentials`, `signature`, `session`, `auth`, `authorization` or `authentication`, or the parts `api-key`, `access-key`, `private-key`, `auth-key`, `subscription-key`, `functions-key`, `application-key`, `app-key`, `master-key`, `client-key` or `partner-key` (`X-Api-Key`, `X-Auth-Token`), is refused (`invalid-mcp-endpoint`, reason `credential-in-headers`). Send it by reference: `auth` with `scheme: header`, or `secretRef` for a bearer. An endpoint registered with one before keeps working, and its value reads back as `[redacted]`.

  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

- **object**

  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

- **object**

  OAuth 2 client credentials: the runtime asks `tokenUrl` for an access token (`grant_type=client_credentials`) as `clientId`, with the client secret `secretRef` names, sends it as the endpoint’s bearer, and asks for a new one before it expires (Drupal’s Simple OAuth, for one). The token is never stored.

  object

  **scheme**

  required

  Allowed value: oauth2-client-credentials

  **tokenUrl**

  required

  The token endpoint: https, or http to a loopback host (`localhost`, `127.0.0.1`, `[::1]`).

  string format: uri

  <= 2048 characters

  **clientId**

  required

  string

  \>= 1 characters <= 512 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

  **scope**

  The scopes to ask for, space-separated, sent as-is. Absent: none asked for.

  string

  \>= 1 characters <= 1024 characters

  **audience**

  An `audience` parameter, for identity providers that need one. Absent: none sent.

  string

  \>= 1 characters <= 1024 characters

  **clientAuth**

  How the client authenticates to the token endpoint (RFC 6749 §2.3.1): `client_secret_basic` (an `Authorization: Basic` header, the default) or `client_secret_post` (`client_id` and `client_secret` in the form).

  string

  Allowed values: client_secret_basic client_secret_post

- **object**

  Headers of the server’s own, each with a secret: an API key in `X-Api-Key`, a key and a secret in two headers, or `Authorization` with a prefix other than `Bearer `(`Token …`). The runtime resolves each `secretRef` when it connects, and refuses to follow a redirect with them, as it does for every `auth`.

  object

  **scheme**

  required

  Allowed value: header

  **headers**

  required

  Array\<object>

  \>= 1 items <= 4 items

  One header a `header` auth sends: `<name>: <prefix><secret>`.

  object

  **name**

  required

  An HTTP header name, once per `auth` (case-insensitive). Not one the MCP transport or HTTP sets itself (`Host`, `Content-Type`, `Content-Length`, `Accept`, `Connection`, `Mcp-Session-Id`, `Mcp-Protocol-Version`, `Last-Event-ID`, `traceparent`, `tracestate`, …): reason `invalid-auth`.

  string

  \>= 1 characters <= 256 characters /^\[!#$%&'\*+.^\_\`|\~0-9A-Za-z-]+$/

  **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

  **prefix**

  Text sent before the secret, such as `Token `or `ApiKey `, without control characters. Absent: none. Not a secret: it reads back as registered.

  string

  \>= 1 characters <= 64 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:

- **object**

  One of:

  - **object**

    object

    **kind**

    required

    string

    Allowed value: tenant

  - **object**

    object

    **kind**

    required

    string

    Allowed value: org

    **orgId**

    required

    string format: uuid

  - **object**

    object

    **kind**

    required

    string

    Allowed value: project

    **projectId**

    required

    string format: uuid

- **null**

  null

**nextCursor**

string

**hasMore**

required

boolean

##### Example

```json
{
  "data": [
    {
      "transport": "stdio",
      "config": {
        "transport": "stdio"
      },
      "auth": {
        "scheme": "basic"
      },
      "secretScopes": {
        "additionalProperty": {
          "kind": "tenant"
        }
      }
    }
  ]
}
```

### 400

Malformed query parameter.

application/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

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

### 401

Missing / malformed / expired / revoked bearer token.

application/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

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

## See also

- [`POST /v1/mcp/endpoints`: Register an MCP endpoint](https://docs.kindgi.com/v0.1.10/reference/api/operations/mcpendpointsregister.md)
- [`GET /v1/mcp/endpoints/{endpointId}`: Fetch an MCP endpoint](https://docs.kindgi.com/v0.1.10/reference/api/operations/mcpendpointsget.md)
- [`POST /v1/mcp/endpoints/{endpointId}/unregister`: Unregister an MCP endpoint](https://docs.kindgi.com/v0.1.10/reference/api/operations/mcpendpointsunregister.md)
- [`GET /v1/mcp/endpoints/{endpointId}/resources`: List resources at a remote MCP endpoint](https://docs.kindgi.com/v0.1.10/reference/api/operations/mcpendpointsresourceslist.md)
- [Kindgi 0.1.10](https://docs.kindgi.com/v0.1.10/releases/0.1.10.md)
- [Every error code](https://docs.kindgi.com/v0.1.10/reference/errors.md)