Register an MCP endpoint

POST

/v1/mcp/endpoints

curl --request POST \
  --url https://example.com/v1/mcp/endpoints \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "endpointId": "example", "name": "example", "transport": "stdio", "config": { "transport": "stdio", "command": "example", "args": [ "example" ], "env": { "additionalProperty": "example" } }, "secretRef": { "envName": "example", "name": "example" }, "instructions": "example", "metadata": {}, "scopeKind": "tenant", "scopeId": "example" }'

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

Body is a full MCPEndpoint plus the scope to register it in (scopeKind + scopeId); authorization checks that scope. Server validates the closed transport enum + the config.transport matches transport guardrail + per-variant required fields (command for stdio; url for http-sse / streamable-http), and refuses unknown fields. secretRef names a secret in the deployment’s store — plaintext secrets never cross the wire. A deployment with KINDGI_TENANT_HOST_ACCESS=deployed (the default outside development) refuses a stdio endpoint, which would run a command on the server’s host: 403 host-access-denied.

Authorizations

• bearerAuth

Parameters

Header Parameters

Idempotency-Key

string

>= 1 characters

Caller-supplied idempotency key. Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1).

Request Body^required

Media typeapplication/json

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

scopeKind

required

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

string

Allowed values: tenant org project

scopeId

Required when scopeKind is org or project; absent for tenant (implicit from the session).

string

>= 1 characters

Responses

201

MCP endpoint registered.

Media typeapplication/json

object

endpointId

required

string

Example^generated

{
  "endpointId": "example"
}

400

Validation failed (see details.reason).

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"
  }
}

403

host-access-denied: a stdio endpoint on a deployment that refuses commands on its host (KINDGI_TENANT_HOST_ACCESS=deployed); or authz-denied.

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"
  }
}

409

MCP endpoint already registered at that id.

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"
  }
}

500

Server error (unmapped domain code or framework crash).

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"
  }
}