> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpmanager.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosts

> Admin API operations for hosts and their gateway connections: create, rename, enable, disable, and delete hosts, and list, inspect, enable, and disable the connections between a host and a gateway.

These operations manage hosts (the apps and agents that connect to gateways) and their connections. Inspecting a single connection returns its last successful tool call and recent errors, so you can debug a failing connection without correlating separate log and alert queries.

<Info>
  **Closed beta.** The MCP Manager Admin API and MCP server are available now to a
  limited set of workspaces through the **MCP Manager Admin API** entitlement
  (`ff-mcpm-admin`), ahead of general availability. If you don't see **Settings →
  MCP & API** in your workspace, it isn't enabled for you yet — ask your MCP Manager
  contact to join the beta.
</Info>

## List Hosts

<Badge color="green">Read-only</Badge>

List the workspace’s hosts.

Returns each host as `{ guid, name, enabled, authenticationType }`, scoped to what the caller may see, like the hosts page.

**MCP tool:** `list_hosts` · **REST:** `GET /api/v1/mcpm-admin/hosts` · **Capability:** Create and manage API tokens (`createAndManageApiTokens`)

**Parameters:** none.

**Example**

```json theme={null}
{}
```

## Create Host

Create an API-token host.

Creates an enabled API-token host (the kind a token connects through). Returns `{ guid, name, enabled, authenticationType }`. To mint a usable token for a gateway, use issue\_gateway\_token.

**MCP tool:** `create_host` · **REST:** `POST /api/v1/mcpm-admin/hosts` · **Capability:** Create and manage API tokens (`createAndManageApiTokens`)

**Parameters**

<ParamField body="name" type="string" required>
  A human-readable name for the host (e.g. "CI runner").
</ParamField>

**Example**

```json theme={null}
{"name":"CI runner"}
```

## Rename Host

Rename a host.

Renames the host. Saved only when the name actually changes. Returns `{ guid, name, enabled, authenticationType }`.

**MCP tool:** `rename_host` · **REST:** `PATCH /api/v1/mcpm-admin/hosts/:hostGuid/name` · **Capability:** Create and manage API tokens (`createAndManageApiTokens`)

**Parameters**

<ParamField path="hostGuid" type="string" required>
  The guid of the host to rename (from list\_hosts).
</ParamField>

<ParamField body="newName" type="string" required>
  The new name for the host.
</ParamField>

**Example**

```json theme={null}
{"hostGuid":"MPH-...","newName":"Release runner"}
```

## Enable Host

Enable a host.

Sets the host to enabled. Saved only when the state changes. Returns `{ guid, name, enabled, authenticationType }`.

**MCP tool:** `enable_host` · **REST:** `POST /api/v1/mcpm-admin/hosts/:hostGuid/enable` · **Capability:** Disable and enable hosts (`enableDisableHosts`)

**Parameters**

<ParamField path="hostGuid" type="string" required>
  The guid of the host to enable (from list\_hosts).
</ParamField>

**Example**

```json theme={null}
{"hostGuid":"MPH-..."}
```

## Disable Host

Disable a host.

Sets the host to disabled. Saved only when the state changes. Returns `{ guid, name, enabled, authenticationType }`.

**MCP tool:** `disable_host` · **REST:** `POST /api/v1/mcpm-admin/hosts/:hostGuid/disable` · **Capability:** Disable and enable hosts (`enableDisableHosts`)

**Parameters**

<ParamField path="hostGuid" type="string" required>
  The guid of the host to disable (from list\_hosts).
</ParamField>

**Example**

```json theme={null}
{"hostGuid":"MPH-..."}
```

## Delete Host

<Badge color="red">Destructive</Badge>

Delete a host.

Hard-deletes the host. Returns `{ deleted: true, hostGuid }`.

**MCP tool:** `delete_host` · **REST:** `DELETE /api/v1/mcpm-admin/hosts/:hostGuid` · **Capability:** Delete hosts (`deleteHosts`)

**Parameters**

<ParamField path="hostGuid" type="string" required>
  The guid of the host to delete (from list\_hosts).
</ParamField>

**Example**

```json theme={null}
{"hostGuid":"MPH-..."}
```

## List Connections

<Badge color="green">Read-only</Badge>

List gateway connections, optionally filtered by host, gateway, or user.

Lists the gateway connections in the workspace — each is a host's live connection to a gateway, established when a token was issued. Filter by hostGuid, gatewayGuid, and/or userGuid (the establishing user). Returns `{ guid, name, enabled, gatewayGuid, hostGuid, creatorGuid }` per connection; use get\_connection for detail and last-activity.

**MCP tool:** `list_connections` · **REST:** `GET /api/v1/mcpm-admin/connections` · **Capability:** Disable and enable connections (`enableDisableConnections`)

**Parameters**

<ParamField query="hostGuid" type="string">
  Only return connections for this host (from list\_hosts).
</ParamField>

<ParamField query="gatewayGuid" type="string">
  Only return connections for this gateway (from list\_gateways).
</ParamField>

<ParamField query="userGuid" type="string">
  Only return connections established by this user (from list\_users).
</ParamField>

**Example**

```json theme={null}
{"hostGuid":"MHO-..."}
```

## Get Connection

<Badge color="green">Read-only</Badge>

Inspect one connection, including its last successful call and recent errors.

Returns full detail for a connection: the summary fields plus the resolved gateway/host names and the establishing user's email, how many servers it carries, and — to debug a failing connection — the date of its last successful call (`lastSuccessfulCallAt`) and its `recentErrors` (from the connection's MCP call logs). No separate log/alert query is needed.

**MCP tool:** `get_connection` · **REST:** `GET /api/v1/mcpm-admin/connections/:connectionGuid` · **Capability:** Disable and enable connections (`enableDisableConnections`)

**Parameters**

<ParamField path="connectionGuid" type="string" required>
  The guid of the connection to inspect (from list\_connections).
</ParamField>

**Example**

```json theme={null}
{"connectionGuid":"MGC-..."}
```

## Disable Connection

Disable a connection.

Cuts off the connection without deleting it (sets enabled=false). Saved only when the state changes. Returns the connection summary.

**MCP tool:** `disable_connection` · **REST:** `POST /api/v1/mcpm-admin/connections/:connectionGuid/disable` · **Capability:** Disable and enable connections (`enableDisableConnections`)

**Parameters**

<ParamField path="connectionGuid" type="string" required>
  The guid of the connection to disable (from list\_connections).
</ParamField>

**Example**

```json theme={null}
{"connectionGuid":"MGC-..."}
```

## Enable Connection

Enable a connection.

Re-enables a previously disabled connection (sets enabled=true). Saved only when the state changes. Returns the connection summary.

**MCP tool:** `enable_connection` · **REST:** `POST /api/v1/mcpm-admin/connections/:connectionGuid/enable` · **Capability:** Disable and enable connections (`enableDisableConnections`)

**Parameters**

<ParamField path="connectionGuid" type="string" required>
  The guid of the connection to enable (from list\_connections).
</ParamField>

**Example**

```json theme={null}
{"connectionGuid":"MGC-..."}
```

## Further reading

<CardGroup cols={2}>
  <Card title="Logging" icon="arrow-right" href="/admin-api/reference/logging">
    Where to go next in this section.
  </Card>

  <Card title="Authentication & access" icon="shield-halved" href="/admin-api/authentication">
    Tokens, the entitlement, capability gating, and error codes for every operation here.
  </Card>

  <Card title="Tool & endpoint reference" icon="book" href="/admin-api/reference/overview">
    The full reference index across every domain.
  </Card>

  <Card title="Capabilities" icon="key" href="/deployment/rbac-and-roles/capabilities">
    What each capability named on this page actually allows.
  </Card>
</CardGroup>