MCP servers

Generated from contract version 1.0.0 — the same document /v1/api/openapi.json serves.

Prerequisites

• An API key in x-api-key, or a browser session cookie
• X-Organization-Id naming the workspace to act in, unless the session already has an active one
• The base URL for your deployment, https://server.hlix.ai by default

Operations

Method	Path	Operation
GET	/v1/api/mcp-servers	List the workspace’s MCP servers
POST	/v1/api/mcp-servers	Register an MCP server
DELETE	/v1/api/mcp-servers/{id}	Delete an MCP server
GET	/v1/api/mcp-servers/{id}	Get one MCP server
PATCH	/v1/api/mcp-servers/{id}	Update an MCP server

List the workspace’s MCP servers

GET /v1/api/mcp-servers · operation ID listMcpServers

Parameters

Name	In	Required	Type	Description
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Responses

Status	Body	Description
200	McpServer[]	Every registered server, enabled or not. env values are write-only: each key is listed and every value reads as an empty string.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

Register an MCP server

POST /v1/api/mcp-servers · operation ID createMcpServer

Parameters

Name	In	Required	Type	Description
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Request body — application/json, CreateMcpServer (required)

Property	Type	Required	Notes
args	string[]	null	no
command	string	null	no
description	string	null	no
enabled	boolean	no
env	object	null	no
name	string	yes	min length 1, max length 100
transport	stdio	http	sse
url	string (uri)	null	no

Responses

Status	Body	Description
201	McpServer	The stored row.
400	ValidationError | ApiError	The JSON body failed schema validation (ValidationError), or the request named no active organization (ApiError).
401	ApiError	No valid session or API key.
403	ApiError	Writing the registry is owner/admin only. (Or the caller is not a member of this workspace at all.)
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
500	ApiError	The server could not be written.

Delete an MCP server

DELETE /v1/api/mcp-servers/{id} · operation ID deleteMcpServer

Parameters

Name	In	Required	Type	Description
id	path	yes	string
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Responses

Status	Body	Description
200	MessageAck	The server is gone.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Writing the registry is owner/admin only. (Or the caller is not a member of this workspace at all.)
404	ApiError	No such MCP server in this workspace.

Get one MCP server

GET /v1/api/mcp-servers/{id} · operation ID getMcpServer

Parameters

Name	In	Required	Type	Description
id	path	yes	string
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Responses

Status	Body	Description
200	McpServer	The row.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	No such MCP server in this workspace.

Update an MCP server

PATCH /v1/api/mcp-servers/{id} · operation ID updateMcpServer

Parameters

Name	In	Required	Type	Description
id	path	yes	string
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Request body — application/json, UpdateMcpServer (required)

Property	Type	Required	Notes
args	string[]	null	no
command	string	null	no
description	string	null	no
enabled	boolean	no
env	object	null	no
name	string	no	min length 1, max length 100
transport	stdio	http	sse
url	string (uri)	null	no

Responses

Status	Body	Description
200	McpServer	The updated row. An env value sent as an empty string keeps the stored value for that key.
400	ValidationError | ApiError	The JSON body failed schema validation (ValidationError), or the request named no active organization (ApiError).
401	ApiError	No valid session or API key.
403	ApiError	Writing the registry is owner/admin only. (Or the caller is not a member of this workspace at all.)
404	ApiError	No such MCP server in this workspace.

If a request fails

These apply to every operation on this page.

• 400 — the body failed schema validation, or the request named no active organization. A ValidationError body carries the failing fields; an ApiError body carries only error.
• 401 — no valid session or API key.
• 403 — authenticated, but not a member of the named organization, or a client collaborator without the required access.
• 404 — no such resource in this workspace. Absent and not-visible are deliberately the same answer; do not infer cross-tenant existence from it.
• 409 — the expected revision or state is stale, or another operation currently owns the transition.
• 500 — the operation failed server-side. Retry only where an idempotency key makes that safe.

Next steps

API referenceEvery resource in the published contract, and what is deliberately not in it.

API & OpenAPIDownload the contract, generate a client, and read the compatibility policy.

TypeScript SDKAuth, retries, typed errors, uploads and streaming, already built.

CLI referenceThe same operations from a terminal, with a stable JSON envelope.