---
title: "Register a new client"
method: POST
path: "/api/v1beta/clients"
tags: ["clients"]
---

# Register a new client

`POST /api/v1beta/clients`

Register a new client with ToolHive

## Request body

- union
  - object
  - PkgApiV1CreateClientRequest
    - `groups` string[] — Groups is the list of groups configured on the client.
    - `name` 'roo-code' | 'cline' | 'cursor' | 'vscode-insider' | 'vscode' | 'claude-code' | 'windsurf' | 'windsurf-jetbrains' | 'amp-cli' | 'amp-vscode' | 'amp-cursor' | 'amp-vscode-insider' | 'amp-windsurf' | 'lm-studio' | 'goose' | 'trae' | 'continue' | 'opencode' | 'kiro' | 'antigravity' | 'zed' | 'gemini-cli' | 'vscode-server' | 'mistral-vibe' | 'codex' — ClientType is the type of MCP client

## Response `200`

OK

- PkgApiV1CreateClientResponse
  - `groups` string[] — Groups is the list of groups configured on the client.
  - `name` 'roo-code' | 'cline' | 'cursor' | 'vscode-insider' | 'vscode' | 'claude-code' | 'windsurf' | 'windsurf-jetbrains' | 'amp-cli' | 'amp-vscode' | 'amp-cursor' | 'amp-vscode-insider' | 'amp-windsurf' | 'lm-studio' | 'goose' | 'trae' | 'continue' | 'opencode' | 'kiro' | 'antigravity' | 'zed' | 'gemini-cli' | 'vscode-server' | 'mistral-vibe' | 'codex' — ClientType is the type of MCP client

## Other responses

- `400` — Invalid request or unsupported client type

## Changes

- **2026-03-17** `8ab2f5690c97` — 1 breaking, 1 info
  - removed `#/components/schemas/v1.createClientRequest` from the request body `oneOf` list
  - added `#/components/schemas/pkg_api_v1.createClientRequest` to the request body `oneOf` list
- **2026-02-09** `a00c1abcef71` — 3 warning, 3 info
  - added the new `codex` enum value to the `name` response property for the response status `200`
  - added the new `mistral-vibe` enum value to the `name` response property for the response status `200`
  - added the new `vscode-server` enum value to the `name` response property for the response status `200`
  - added the new `codex` enum value to the request property `oneOf[#/components/schemas/v1.createClientRequest]/name`
  - …2 more
- **2026-02-05** `0ab796b83fa1` — 1 warning, 1 info
  - added the new `gemini-cli` enum value to the `name` response property for the response status `200`
  - added the new `gemini-cli` enum value to the request property `oneOf[#/components/schemas/v1.createClientRequest]/name`
- …earlier changes not shown

[Full history](https://skmtc.dev/stacklok/apis/toolhive-api/changes/api/v1beta/clients/post.md)

---

[API](https://skmtc.dev/stacklok/apis/toolhive-api.md) · [All operations](https://skmtc.dev/stacklok/apis/toolhive-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/stacklok/toolhive-api/revisions/3b31034fd29e/schema)