MCP Servers¶

Create MCP server metadata¶

POST /mcp-servers

Code samples

curl -X POST https://localhost:9543/api/v0.9/mcp-servers \
  -u {username}:{password} \
  -H 'Content-Type: multipart/form-data' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Creates Developer Portal MCP server metadata. Accepts the same metadata input formats as POST /api/v0.9/apis (artifact ZIP, api.yaml / devportal.yaml / mcp.yaml, or metadata JSON), but the created record is always typed MCP. An MCP server's contract is its definition (tools schema) — the tools, resources, and prompts it exposes — not an OpenAPI-style API contract; a definition is required. Via the JSON metadata field, type must be explicitly MCP; an omitted type or any other value is rejected with a 400 (use POST /api/v0.9/apis).

Payload

artifact: string
definition: string
metadata: '{"name":"Travel Assistant MCP","version":"v1","description":"MCP
  server for travel planning
  tools","type":"MCP","agentVisibility":"VISIBLE","status":"PUBLISHED",
  "tags":["mcp"],"labels":["default"],"endPoints":{"productionURL":"https://mcp.example.com",
  "sandboxURL":"https://mcp.example.com"},"subscriptionPlans":[{"id":"Gold"}]}'

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	object	true	MCP server upload. Provide the server metadata via `metadata` (a JSON string or an uploaded YAML/JSON file), or a full `artifact` ZIP, together with its `definition` — the tools, resources, and prompts the server exposes. An MCP server has no OpenAPI-style API contract; its `definition` (tools schema) IS its contract, so it is required on create (and replaces the stored schema when supplied on update).
» artifact	body	string(binary)	false	Full MCP server ZIP artifact containing the metadata and the definition.
» definition	body	string(binary)	false	MCP tools schema (YAML or JSON) listing the tools, resources, and prompts the server exposes. Required on create; when supplied on update it replaces the stored schema.
» metadata	body	string	false	MCP server metadata, supplied either as a JSON string field or as an uploaded YAML/JSON file (a k8s-style document of kind `MCP`; file names `metadata.yaml`/`.yml`/`.json`, or the legacy `api.yaml`/`mcp.yaml`/`devportal.yaml`). As a JSON string it accepts these top-level fields: `name`, `version`, `description`, `type` (must be `MCP`), `agentVisibility`, `status`, `referenceId`, `id`, `tags`, `labels`, `owners`, `endPoints` (productionURL, sandboxURL), and `subscriptionPlans` (array of `{ id }` objects — only `id` is read; the plan must already exist in the organization). `id` becomes the MCP server's stored handle.

Example responses

201 Response

{
  "id": "weather-api-v1",
  "refId": "cp-api-12345",
  "name": "Weather API",
  "title": "Weather Forecast API",
  "version": "v1",
  "status": "PUBLISHED",
  "description": "Weather forecast API.",
  "type": "MCP",
  "agentVisibility": "VISIBLE",
  "tags": [
    "weather"
  ],
  "labels": [
    "default"
  ],
  "endPoints": {
    "productionURL": "https://api.example.com/weather",
    "sandboxURL": "https://sandbox.example.com/weather"
  },
  "subscriptionPlans": [
    {
      "id": "Gold"
    }
  ]
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Conflict"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
201	Created	Created MCP server metadata payload returned by the service. Always typed `MCP`.	ApiMetadataCreateResponse
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
404	Not Found	Resource not found.	ErrorResponse
409	Conflict	The request conflicts with an existing resource.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error

Response Headers¶

Status	Header	Type	Format	Description
201	Location	string	uri	URL of the created MCP server metadata resource.

List MCP server metadata¶

GET /mcp-servers

Code samples

curl -X GET https://localhost:9543/api/v0.9/mcp-servers \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Lists MCP server metadata for an organization. Mirrors GET /api/v0.9/apis but only returns MCP-typed records.

Authentication¶

Parameters

Name	In	Type	Required	Description
query	query	string	false	Free-text API metadata search term.
name	query	string	false	Exact API name filter.
version	query	string	false	Exact API version filter.
tags	query	string	false	Comma-separated tag names. Matches APIs tagged with any of the given names.
view	query	string	false	Developer Portal view name used to filter visible APIs.
limit	query	integer	false	Maximum number of records to return.
offset	query	integer	false	Number of records to skip before returning results.

Example responses

200 Response

{
  "list": [
    {
      "id": "weather-api-v1",
      "refId": "cp-api-12345",
      "name": "Weather API",
      "version": "v1",
      "status": "PUBLISHED",
      "description": "Weather forecast API.",
      "type": "MCP",
      "agentVisibility": "VISIBLE",
      "labels": [
        "default"
      ],
      "endPoints": {
        "sandboxURL": "https://sandbox.example.com/weather",
        "productionURL": "https://api.example.com/weather"
      }
    }
  ],
  "count": 1,
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	List of MCP server metadata DTOs. Always typed `MCP`.	Inline
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» list	[allOf]	false	none	none

allOf

Name	Type	Required	Restrictions	Description
»» anonymous	ApiInfoResponse	false	none	Fields are returned at the root of ApiMetadataResponse / ApiMetadataCreateResponse (not nested under an `apiInfo` key) — this schema exists only to share the field set between the two via `allOf`.
»»» name	string	false	none	none
»»» title	string¦null	false	none	none
»»» remotes	[object]	false	none	none
»»» version	string	false	none	none
»»» status	string	false	none	API lifecycle status.
»»» description	string	false	none	none
»»» type	string	false	none	The stored/returned type constant (src/utils/constants.js API_TYPE) — distinct from the request-time keyword accepted on create/update (see `type` in ApiMetadataMultipartBody: REST, SOAP, MCP, WS, WEBSUB, GRAPHQL). REST maps to `RestApi` and WEBSUB maps to `WebSubApi`; the rest are returned unchanged.
»»» referenceId	string¦null	false	none	External reference ID. Present when the API was created from a `devportal.yaml` artifact whose `spec` block sets `referenceId` — the create response echoes the parsed YAML back.
»»» agentVisibility	string	false	none	none
»»» addedLabels	[string]	false	none	none
»»» removedLabels	[string]	false	none	none
»»» owners	ApiOwnersResponse	false	none	none
»»»» technicalOwner	string	false	none	none
»»»» businessOwner	string	false	none	none
»»»» businessOwnerEmail	string	false	none	none
»»»» technicalOwnerEmail	string	false	none	none
»»» apiImageMetadata	ApiImageMetadataResponse	false	none	none
»»»» additionalProperties	string	false	none	none
»»» tags	[string]	false	none	none
»»» labels	[string]	false	none	none

and

Name	Type	Required	Restrictions	Description
»» anonymous	object	false	none	none
»»» id	string	false	none	The API's handle (unique per org). Not the internal database uuid.
»»» refId	string¦null	false	none	Platform API (Control Plane) reference ID for this API. Used for MCP registry visibility filtering and included in outbound webhook event payloads. Null/absent for APIs that exist only in the Developer Portal and are not registered with the Platform API — e.g. MCP servers published via the registry.
»»» dataSource	string¦null	false	none	Indicates which content matched the search term: `METADATA` if the match was in the API's own metadata, or a content type (e.g. a value from the API Content `type` field) if the match was inside an uploaded content file. Only computed by getAllApiMetadataForOrganization when both the `query` search parameter is supplied and the database is PostgreSQL — absent on SQLite (the dev default) and absent from every other operation (get/create/update single API).
»»» planId	string	false	none	none
»»» endPoints	ApiEndpointsResponse	false	none	none
»»»» sandboxURL	string	false	none	none
»»»» productionURL	string	false	none	none
»»» subscriptionPlans	[SubscriptionPlanResponse]	false	none	none
»»»» id	string	false	none	The plan's handle (unique per org). Not the internal database uuid.
»»»» displayName	string	false	none	none
»»»» description	string	false	none	none
»»»» limits	[object]	false	none	Rate/quota limits enforced for this plan. Empty when the plan is unlimited.
»»»»» limitType	string	false	none	none
»»»»» limitCount	any	false	none	Returned as a string when the stored count exceeds the safe integer range, otherwise a number. Unlimited plans have no limit entries — the `limits` array is empty.

oneOf

Name	Type	Required	Restrictions	Description
»»»»»» anonymous	integer	false	none	none

xor

Name	Type	Required	Restrictions	Description
»»»»»» anonymous	string	false	none	none

continued

Name	Type	Required	Restrictions	Description
»»»»» timeUnit	string¦null	false	none	none
»»»»» timeAmount	integer	false	none	none
»»»» refId	string¦null	false	none	Platform API subscription plan UUID associated with this plan.
»»»» orgId	string	false	none	none
»»»» createdBy	string	false	none	Identity of the user who created this subscription plan, or `deleted_user` if that user's IDP reference no longer exists. Present on single-resource GET responses and list items.
»»»» updatedBy	string	false	none	Identity of the user who last updated this subscription plan, or `deleted_user` if that user's IDP reference no longer exists. Present on single-resource GET responses only, omitted on list items.
»»»» createdAt	string(date-time)	false	none	none
»»»» updatedAt	string(date-time)	false	none	none
»»» createdBy	string	false	none	Identity of the user who created this API, or `deleted_user` if that user's IDP reference no longer exists. Present on single-resource GET responses and list items.
»»» updatedBy	string	false	none	Identity of the user who last updated this API, or `deleted_user` if that user's IDP reference no longer exists. Present on single-resource GET responses only, omitted on list items.
»»» createdAt	string(date-time)	false	none	none
»»» updatedAt	string(date-time)	false	none	none
» count	integer	false	none	Number of items returned in this page.
» pagination	Pagination	false	none	Standard pagination metadata returned with collection responses.
»» total	integer	true	none	Total number of records matching the query.
»» limit	integer	true	none	Maximum number of records returned in this response.
»» offset	integer	true	none	Number of records skipped before this page.

Enumerated Values

Property	Value
status	PUBLISHED
status	DEPRECATED
type	RestApi
type	SOAP
type	Mcp
type	WS
type	WebSubApi
type	GRAPHQL
agentVisibility	VISIBLE
agentVisibility	HIDDEN
limitType	REQUEST_COUNT
limitType	EVENT_COUNT
limitType	BANDWIDTH
limitType	TOTAL_TOKEN_COUNT
timeUnit	MINUTE
timeUnit	HOUR
timeUnit	DAY
timeUnit	MONTH
timeUnit	null

Enumerated Values

Property	Value
status	error

Get MCP server metadata¶

GET /mcp-servers/{mcpServerId}

Code samples

curl -X GET https://localhost:9543/api/v0.9/mcp-servers/{mcpServerId} \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Retrieves a single MCP server metadata record by Developer Portal MCP server ID.

Authentication¶

Parameters

Name	In	Type	Required	Description
mcpServerId	path	string	true	The MCP server's handle (unique per org).

Example responses

200 Response

{
  "id": "weather-api-v1",
  "refId": "cp-api-12345",
  "name": "Weather API",
  "title": "Weather Forecast API",
  "remotes": [],
  "version": "v1",
  "status": "PUBLISHED",
  "description": "Weather forecast API.",
  "type": "MCP",
  "agentVisibility": "VISIBLE",
  "labels": [
    "default"
  ],
  "endPoints": {
    "sandboxURL": "https://sandbox.example.com/weather",
    "productionURL": "https://api.example.com/weather"
  },
  "subscriptionPlans": [
    {
      "id": "Gold"
    }
  ]
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

404 Response

"string"

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	MCP server metadata DTO returned by the service. Always typed `MCP`.	ApiMetadataResponse
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
404	Not Found	Plain text success response.	string
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error

Update MCP server metadata¶

PUT /mcp-servers/{mcpServerId}

Code samples

curl -X PUT https://localhost:9543/api/v0.9/mcp-servers/{mcpServerId} \
  -u {username}:{password} \
  -H 'Content-Type: multipart/form-data' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Updates Developer Portal MCP server metadata and, when a definition is supplied, its stored tools schema. type is required and immutable — it must stay MCP; any other value is rejected with 400 via the same resolveTypeOrReject check POST /mcp-servers uses. An MCP server's definition is its tools schema, not an OpenAPI-style API contract.

Payload

artifact: string
definition: string
metadata: '{"name":"Travel Assistant MCP","version":"v1","description":"MCP
  server for travel planning
  tools","type":"MCP","agentVisibility":"VISIBLE","status":"PUBLISHED",
  "tags":["mcp"],"labels":["default"],"endPoints":{"productionURL":"https://mcp.example.com",
  "sandboxURL":"https://mcp.example.com"},"subscriptionPlans":[{"id":"Gold"}]}'

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	object	true	MCP server upload. Provide the server metadata via `metadata` (a JSON string or an uploaded YAML/JSON file), or a full `artifact` ZIP, together with its `definition` — the tools, resources, and prompts the server exposes. An MCP server has no OpenAPI-style API contract; its `definition` (tools schema) IS its contract, so it is required on create (and replaces the stored schema when supplied on update).
» artifact	body	string(binary)	false	Full MCP server ZIP artifact containing the metadata and the definition.
» definition	body	string(binary)	false	MCP tools schema (YAML or JSON) listing the tools, resources, and prompts the server exposes. Required on create; when supplied on update it replaces the stored schema.
» metadata	body	string	false	MCP server metadata, supplied either as a JSON string field or as an uploaded YAML/JSON file (a k8s-style document of kind `MCP`; file names `metadata.yaml`/`.yml`/`.json`, or the legacy `api.yaml`/`mcp.yaml`/`devportal.yaml`). As a JSON string it accepts these top-level fields: `name`, `version`, `description`, `type` (must be `MCP`), `agentVisibility`, `status`, `referenceId`, `id`, `tags`, `labels`, `owners`, `endPoints` (productionURL, sandboxURL), and `subscriptionPlans` (array of `{ id }` objects — only `id` is read; the plan must already exist in the organization). `id` becomes the MCP server's stored handle.
mcpServerId	path	string	true	The MCP server's handle (unique per org).

Example responses

200 Response

{
  "id": "weather-api-v1",
  "refId": "cp-api-12345",
  "name": "Weather API",
  "title": "Weather Forecast API",
  "remotes": [],
  "version": "v1",
  "status": "PUBLISHED",
  "description": "Weather forecast API.",
  "type": "MCP",
  "agentVisibility": "VISIBLE",
  "labels": [
    "default"
  ],
  "endPoints": {
    "sandboxURL": "https://sandbox.example.com/weather",
    "productionURL": "https://api.example.com/weather"
  },
  "subscriptionPlans": [
    {
      "id": "Gold"
    }
  ]
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Conflict"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	MCP server metadata DTO returned by the service. Always typed `MCP`.	ApiMetadataResponse
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
404	Not Found	Resource not found.	ErrorResponse
409	Conflict	The request conflicts with an existing resource.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error

Delete MCP server metadata¶

DELETE /mcp-servers/{mcpServerId}

Code samples

curl -X DELETE https://localhost:9543/api/v0.9/mcp-servers/{mcpServerId} \
  -u {username}:{password} \
  -H 'Accept: text/plain' \
  -H 'Authorization: Bearer {access-token}'

Deletes MCP server metadata when the MCP server has no active subscriptions.

Authentication¶

Parameters

Name	In	Type	Required	Description
mcpServerId	path	string	true	The MCP server's handle (unique per org).

Example responses

200 Response

"string"

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Conflict"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	Plain text success response.	string
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
404	Not Found	Resource not found.	ErrorResponse
409	Conflict	The request conflicts with an existing resource.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error