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

# MCP setup and tool reference

> Connect an agent to your Engine over stdio or authenticated Streamable HTTP.

Nerdit's Model Context Protocol server lets an agent use the same Engine operations as the CLI and HTTP API. Tool results follow the caller's real role, ownership and service scope. This page lists the **49 tools in the 0.6.0 source interface**; an installed server's `tools/list` response is authoritative for its version.

## Connect over stdio

Use a Nerdit installation that includes the MCP extra. For a Python source installation, install the optional dependency in that same environment using the [development setup](/engine/development). If using a binary installation, verify that `nerdit mcp` is available; installing a Python extra separately does not modify a frozen binary.

Add this server entry to your MCP client's configuration, adapting the surrounding configuration format to that client:

```json theme={null}
{
  "mcpServers": {
    "nerdit": {
      "command": "nerdit",
      "args": ["mcp"]
    }
  }
}
```

Use an absolute executable path if your client does not inherit your terminal's PATH. The subprocess reads the same CLI configuration as `nerdit`, including the remote connection and selected credential. The subprocess and Engine do not need to be on the same machine, but any path given to the `deploy` tool is local to the **MCP server process**, not the chat client.

Choose a dedicated scoped token before connecting an agent. See [Security](/engine/security). Do not store tokens in a shared MCP configuration or paste credentials into the conversation.

## Connect over HTTP

The Engine can expose the same tools as Streamable HTTP at `/api/mcp` (with or without a trailing slash). It is off by default. Enable it in the Engine config after setting a real Engine authentication token through the normal secure setup:

```toml theme={null}
[mcp]
http_enabled = true
```

Restart the Engine using your installation's normal management method. It refuses startup when HTTP MCP is enabled without `[daemon].auth_token` or without the MCP dependency. A successful node-link setup can enable this transport when both prerequisites are met.

Configure an HTTP-capable MCP client with the Engine's URL and `Authorization: Bearer …` header. For a same-machine client the default URL is `http://127.0.0.1:9321/api/mcp`. Remote clients need a protected connection and the configured reachable endpoint; enabling the transport does not widen the Engine's loopback bind.

The transport validates Host/Origin and request size. Requests require `Content-Length`; the default body cap is 1 MiB (`[mcp].max_body_bytes`). A readonly token can discover tools and call permitted reads; write calls remain forbidden.

For the account-linked remote gateway, follow the [App connection guide](/app/connect-engine) and use the connection details shown by the App. Do not substitute a local filesystem path for a remote workspace upload.

## Deploy from an agent

1. Call `capabilities` and `doctor` to learn the node's current abilities and the caller's permissions.
2. Choose the source: `deploy` for a folder accessible to the MCP process, `deploy_git` for a permitted Git repository, or `write_app_files` followed by `deploy_app` for agent-authored source.
3. Use `dry_run=true` where supported, inspect the plan, then submit the real deployment.
4. Call `wait_for_service` with its name and returned deployment version. Inspect `diagnose_service` on failure and `service_logs` for selected output.
5. Verify the returned endpoint is reachable from the intended client. A LAN URL is not an internet URL. Hosted sharing and direct domains have separate prerequisites in [Networking and HTTPS](/engine/networking).

A workspace remains available after deployment. Update only the changed text files, then call `deploy_app` again. Files must be UTF-8 text without NUL bytes, bounded to 256 KiB per file, 500 files and 10 MiB total. Use multiple small writes for a larger app; binary assets need a Git or folder source. Workspaces are owner-scoped and survive service deletion unless workspace purge is explicitly requested.

## Safe operation

Tool results can contain an `error` object with a stable code, message and recovery hint. Check for it before proceeding. Deployment acceptance is asynchronous; only a successful wait confirms the deployment outcome.

Most write tools accept an `idempotency_key` and generate one if omitted. Retain an explicit key when retrying the same uncertain operation. Read the [HTTP retry contract](/engine/http-api) before reusing one. `restart_daemon` can close its own HTTP connection during a successful restart: check health before treating that as failure.

<Warning>
  Tools can delete services, publish applications, run commands and change configuration within the supplied credential's permissions. Grant only the access the agent needs. Secret-setting tools keep values out of responses, but values supplied through chat may still enter the client's conversation history; set sensitive values outside chat.
</Warning>

Token creation/rotation, secrets-key rotation, control-plane backups and restores, and database restores are deliberately absent from MCP. Database dumps return metadata for a server-side archive, not its contents. Use the [CLI](/engine/cli) or [HTTP API](/engine/http-api) and the [recovery guide](/engine/backup-recovery) for those operator actions.

## Tool reference

<AccordionGroup>
  <Accordion title="add_domain">
    Serve a deployed app at a domain YOU own, from this node's own proxy.

    | Parameter         | Type           | Required | Default |
    | ----------------- | -------------- | -------- | ------- |
    | `name`            | `string`       | Yes      | `—`     |
    | `domain`          | `string`       | Yes      | `—`     |
    | `acme`            | `boolean/null` | No       | `null`  |
    | `idempotency_key` | `string/null`  | No       | `null`  |
  </Accordion>

  <Accordion title="apply_config">
    Declaratively apply a multi-section daemon config document (all-or-nothing).

    | Parameter         | Type          | Required | Default |
    | ----------------- | ------------- | -------- | ------- |
    | `sections`        | `object`      | Yes      | `—`     |
    | `dry_run`         | `boolean`     | No       | `false` |
    | `if_match`        | `string/null` | No       | `null`  |
    | `idempotency_key` | `string/null` | No       | `null`  |
  </Accordion>

  <Accordion title="capabilities">
    Describe this daemon: version, caller role/quotas, URL grammar, backends.

    No parameters.
  </Accordion>

  <Accordion title="cluster_stats">
    Get aggregate cluster metrics (GPUs in use/total, services up).

    No parameters.
  </Accordion>

  <Accordion title="create_database">
    Provision a managed database (kind=database workload).

    | Parameter         | Type          | Required | Default |
    | ----------------- | ------------- | -------- | ------- |
    | `backend`         | `string/null` | No       | `null`  |
    | `name`            | `string/null` | No       | `null`  |
    | `idempotency_key` | `string/null` | No       | `null`  |
  </Accordion>

  <Accordion title="deploy">
    Use when: the source is a local folder. Asynchronous — follow with wait\_for\_service.

    | Parameter         | Type           | Required | Default |
    | ----------------- | -------------- | -------- | ------- |
    | `path`            | `string/null`  | No       | `null`  |
    | `name`            | `string/null`  | No       | `null`  |
    | `port`            | `integer/null` | No       | `null`  |
    | `gpus`            | `integer/null` | No       | `null`  |
    | `start`           | `string/null`  | No       | `null`  |
    | `health`          | `string/null`  | No       | `null`  |
    | `env`             | `object/null`  | No       | `null`  |
    | `vendor`          | `string/null`  | No       | `null`  |
    | `rollback`        | `boolean`      | No       | `false` |
    | `dry_run`         | `boolean`      | No       | `false` |
    | `idempotency_key` | `string/null`  | No       | `null`  |
  </Accordion>

  <Accordion title="deploy_app">
    Use when: you used write\_app\_files. Asynchronous — follow with wait\_for\_service.

    | Parameter         | Type           | Required | Default |
    | ----------------- | -------------- | -------- | ------- |
    | `name`            | `string`       | Yes      | `—`     |
    | `port`            | `integer/null` | No       | `null`  |
    | `gpus`            | `integer/null` | No       | `null`  |
    | `start`           | `string/null`  | No       | `null`  |
    | `health`          | `string/null`  | No       | `null`  |
    | `env`             | `object/null`  | No       | `null`  |
    | `vendor`          | `string/null`  | No       | `null`  |
    | `dry_run`         | `boolean`      | No       | `false` |
    | `idempotency_key` | `string/null`  | No       | `null`  |
  </Accordion>

  <Accordion title="deploy_git">
    Use when: the app lives in a Git repo. Asynchronous — follow with wait\_for\_service.

    | Parameter         | Type           | Required | Default |
    | ----------------- | -------------- | -------- | ------- |
    | `repo_url`        | `string`       | Yes      | `—`     |
    | `name`            | `string`       | Yes      | `—`     |
    | `ref`             | `string/null`  | No       | `null`  |
    | `subdir`          | `string/null`  | No       | `null`  |
    | `port`            | `integer/null` | No       | `null`  |
    | `gpus`            | `integer/null` | No       | `null`  |
    | `start`           | `string/null`  | No       | `null`  |
    | `health`          | `string/null`  | No       | `null`  |
    | `env`             | `object/null`  | No       | `null`  |
    | `vendor`          | `string/null`  | No       | `null`  |
    | `token_ref`       | `string/null`  | No       | `null`  |
    | `dry_run`         | `boolean`      | No       | `false` |
    | `idempotency_key` | `string/null`  | No       | `null`  |
  </Accordion>

  <Accordion title="deploy_template">
    Use when: you want a starter app. Asynchronous — follow with wait\_for\_service.

    | Parameter         | Type           | Required | Default |
    | ----------------- | -------------- | -------- | ------- |
    | `template_id`     | `string`       | Yes      | `—`     |
    | `name`            | `string`       | Yes      | `—`     |
    | `env`             | `object/null`  | No       | `null`  |
    | `secrets`         | `object/null`  | No       | `null`  |
    | `port`            | `integer/null` | No       | `null`  |
    | `gpus`            | `integer/null` | No       | `null`  |
    | `start`           | `string/null`  | No       | `null`  |
    | `health`          | `string/null`  | No       | `null`  |
    | `vendor`          | `string/null`  | No       | `null`  |
    | `idempotency_key` | `string/null`  | No       | `null`  |
  </Accordion>

  <Accordion title="diagnose_service">
    Use when: a service is failing and you need the reason, not the logs.

    | Parameter  | Type      | Required | Default |
    | ---------- | --------- | -------- | ------- |
    | `name`     | `string`  | Yes      | `—`     |
    | `log_tail` | `integer` | No       | `50`    |
  </Accordion>

  <Accordion title="doctor">
    Run the daemon's bounded environment health checks (docker/gpu/proxy/db/...).

    No parameters.
  </Accordion>

  <Accordion title="dump_database">
    Capture a logical, application-consistent dump of a managed database.

    | Parameter   | Type      | Required | Default |
    | ----------- | --------- | -------- | ------- |
    | `name`      | `string`  | Yes      | `—`     |
    | `timeout_s` | `integer` | No       | `300`   |
  </Accordion>

  <Accordion title="get_app_config">
    Read a deployed app's daemon-persisted config (deploy fields + ai bindings).

    | Parameter | Type     | Required | Default |
    | --------- | -------- | -------- | ------- |
    | `name`    | `string` | Yes      | `—`     |
  </Accordion>

  <Accordion title="get_audit">
    Read the audit log (admin-scoped), bounded to `limit` entries per page.

    | Parameter       | Type          | Required | Default |
    | --------------- | ------------- | -------- | ------- |
    | `action`        | `string/null` | No       | `null`  |
    | `result`        | `string/null` | No       | `null`  |
    | `target`        | `string/null` | No       | `null`  |
    | `target_type`   | `string/null` | No       | `null`  |
    | `principal_id`  | `string/null` | No       | `null`  |
    | `action_prefix` | `string/null` | No       | `null`  |
    | `since`         | `string/null` | No       | `null`  |
    | `until`         | `string/null` | No       | `null`  |
    | `cursor`        | `string/null` | No       | `null`  |
    | `limit`         | `integer`     | No       | `50`    |
  </Accordion>

  <Accordion title="get_config">
    Read daemon config: one section view, or all sections when omitted.

    | Parameter | Type          | Required | Default |
    | --------- | ------------- | -------- | ------- |
    | `section` | `string/null` | No       | `null`  |
  </Accordion>

  <Accordion title="get_events">
    Use when: you need the daemon's own account of what it just did.

    | Parameter  | Type           | Required | Default |
    | ---------- | -------------- | -------- | ------- |
    | `types`    | `string/null`  | No       | `null`  |
    | `service`  | `string/null`  | No       | `null`  |
    | `cursor`   | `string/null`  | No       | `null`  |
    | `since_id` | `integer/null` | No       | `null`  |
    | `limit`    | `integer`      | No       | `50`    |
  </Accordion>

  <Accordion title="get_service">
    Get one service. `name` accepts the service name or the job id.

    | Parameter | Type     | Required | Default |
    | --------- | -------- | -------- | ------- |
    | `name`    | `string` | Yes      | `—`     |
  </Accordion>

  <Accordion title="list_app_files">
    List an app's workspace: paths, sizes, sha256 and totals.

    | Parameter | Type     | Required | Default |
    | --------- | -------- | -------- | ------- |
    | `name`    | `string` | Yes      | `—`     |
  </Accordion>

  <Accordion title="list_app_templates">
    List the app template store — deployable starter apps (id/name/coordinates).

    No parameters.
  </Accordion>

  <Accordion title="list_database_dumps">
    List the dump tars this daemon holds for one managed database.

    | Parameter | Type     | Required | Default |
    | --------- | -------- | -------- | ------- |
    | `name`    | `string` | Yes      | `—`     |
  </Accordion>

  <Accordion title="list_databases">
    List managed databases (kind=database workloads), bounded to `limit` per page.

    | Parameter | Type           | Required | Default |
    | --------- | -------------- | -------- | ------- |
    | `limit`   | `integer/null` | No       | `null`  |
    | `cursor`  | `string/null`  | No       | `null`  |
  </Accordion>

  <Accordion title="list_gpus">
    List GPUs known to the daemon, with live utilization metrics.

    No parameters.
  </Accordion>

  <Accordion title="list_models">
    List served AI models (kind=model workloads), bounded to `limit` per page.

    | Parameter | Type           | Required | Default |
    | --------- | -------------- | -------- | ------- |
    | `limit`   | `integer/null` | No       | `null`  |
    | `cursor`  | `string/null`  | No       | `null`  |
  </Accordion>

  <Accordion title="list_routes">
    List the DB-authoritative route inventory, annotated with live Caddy state.

    | Parameter | Type          | Required | Default |
    | --------- | ------------- | -------- | ------- |
    | `cursor`  | `string/null` | No       | `null`  |
    | `limit`   | `integer`     | No       | `50`    |
  </Accordion>

  <Accordion title="list_secret_names">
    List a service's secret key names (values are never returned).

    | Parameter | Type     | Required | Default |
    | --------- | -------- | -------- | ------- |
    | `service` | `string` | Yes      | `—`     |
  </Accordion>

  <Accordion title="list_services">
    List services, optionally filtered by status, bounded to `limit` per page.

    | Parameter | Type          | Required | Default |
    | --------- | ------------- | -------- | ------- |
    | `status`  | `string/null` | No       | `null`  |
    | `cursor`  | `string/null` | No       | `null`  |
    | `limit`   | `integer`     | No       | `50`    |
  </Accordion>

  <Accordion title="proxy_status">
    Get the embedded proxy's typed state (TLS, apex, respawn, live routes).

    No parameters.
  </Accordion>

  <Accordion title="read_app_file">
    Read one file back from an app's workspace as text.

    | Parameter | Type     | Required | Default |
    | --------- | -------- | -------- | ------- |
    | `name`    | `string` | Yes      | `—`     |
    | `path`    | `string` | Yes      | `—`     |
  </Accordion>

  <Accordion title="redeploy_service">
    Use when: a git app needs a new commit. Asynchronous — follow with wait\_for\_service.

    | Parameter         | Type          | Required | Default |
    | ----------------- | ------------- | -------- | ------- |
    | `name`            | `string`      | Yes      | `—`     |
    | `dry_run`         | `boolean`     | No       | `false` |
    | `idempotency_key` | `string/null` | No       | `null`  |
  </Accordion>

  <Accordion title="remove_domain">
    Remove a custom domain; its route disappears on the next reconcile tick. Idempotent.

    | Parameter         | Type          | Required | Default |
    | ----------------- | ------------- | -------- | ------- |
    | `name`            | `string`      | Yes      | `—`     |
    | `domain`          | `string`      | Yes      | `—`     |
    | `idempotency_key` | `string/null` | No       | `null`  |
  </Accordion>

  <Accordion title="remove_secret">
    Delete one secret key, or all of a service's secrets when key is omitted.

    | Parameter         | Type          | Required | Default |
    | ----------------- | ------------- | -------- | ------- |
    | `service`         | `string`      | Yes      | `—`     |
    | `key`             | `string/null` | No       | `null`  |
    | `idempotency_key` | `string/null` | No       | `null`  |
  </Accordion>

  <Accordion title="remove_service">
    Delete a service (teardown + remove).

    | Parameter         | Type          | Required | Default     |
    | ----------------- | ------------- | -------- | ----------- |
    | `name`            | `string`      | Yes      | `—`         |
    | `purge`           | `string`      | No       | `"secrets"` |
    | `force`           | `boolean`     | No       | `false`     |
    | `idempotency_key` | `string/null` | No       | `null`      |
  </Accordion>

  <Accordion title="restart_daemon">
    Restart the daemon to apply restart-required config (admin-scoped, audited).

    | Parameter         | Type          | Required | Default |
    | ----------------- | ------------- | -------- | ------- |
    | `drain_timeout_s` | `integer`     | No       | `60`    |
    | `idempotency_key` | `string/null` | No       | `null`  |
  </Accordion>

  <Accordion title="restart_service">
    Restart a service (clears backoff).

    | Parameter         | Type          | Required | Default |
    | ----------------- | ------------- | -------- | ------- |
    | `name`            | `string`      | Yes      | `—`     |
    | `idempotency_key` | `string/null` | No       | `null`  |
  </Accordion>

  <Accordion title="run_command">
    Run a one-off command in a deployed service's image (migrations, seeds).

    | Parameter         | Type          | Required | Default |
    | ----------------- | ------------- | -------- | ------- |
    | `name`            | `string`      | Yes      | `—`     |
    | `command`         | `array`       | Yes      | `—`     |
    | `env`             | `object/null` | No       | `null`  |
    | `timeout_s`       | `integer`     | No       | `300`   |
    | `log_tail`        | `integer`     | No       | `200`   |
    | `idempotency_key` | `string/null` | No       | `null`  |
  </Accordion>

  <Accordion title="serve">
    Register a service from a prebuilt image. Idempotency key auto-generated if omitted.

    | Parameter         | Type          | Required | Default    |
    | ----------------- | ------------- | -------- | ---------- |
    | `name`            | `string`      | Yes      | `—`        |
    | `image`           | `string`      | Yes      | `—`        |
    | `port`            | `integer`     | No       | `8000`     |
    | `gpus`            | `integer`     | No       | `0`        |
    | `restart_policy`  | `string`      | No       | `"always"` |
    | `command`         | `string/null` | No       | `null`     |
    | `script_path`     | `string/null` | No       | `null`     |
    | `env`             | `object/null` | No       | `null`     |
    | `vendor`          | `string/null` | No       | `null`     |
    | `health_check`    | `object/null` | No       | `null`     |
    | `idempotency_key` | `string/null` | No       | `null`     |
  </Accordion>

  <Accordion title="serve_model">
    Serve a local AI model as an OpenAI-compatible endpoint.

    | Parameter                | Type           | Required | Default |
    | ------------------------ | -------------- | -------- | ------- |
    | `model`                  | `string`       | Yes      | `—`     |
    | `gpus`                   | `integer`      | No       | `0`     |
    | `name`                   | `string/null`  | No       | `null`  |
    | `backend`                | `string/null`  | No       | `null`  |
    | `max_model_len`          | `integer/null` | No       | `null`  |
    | `gpu_memory_utilization` | `number/null`  | No       | `null`  |
    | `idempotency_key`        | `string/null`  | No       | `null`  |
  </Accordion>

  <Accordion title="service_logs">
    Use when: you need the raw output a service or its build printed.

    | Parameter  | Type          | Required | Default |
    | ---------- | ------------- | -------- | ------- |
    | `name`     | `string`      | Yes      | `—`     |
    | `since_id` | `integer`     | No       | `0`     |
    | `tail`     | `integer`     | No       | `100`   |
    | `grep`     | `string/null` | No       | `null`  |
    | `since`    | `string/null` | No       | `null`  |
    | `source`   | `string`      | No       | `"all"` |
  </Accordion>

  <Accordion title="service_stats">
    Get live CPU, memory, network and PID usage for a running service.

    | Parameter | Type     | Required | Default |
    | --------- | -------- | -------- | ------- |
    | `name`    | `string` | Yes      | `—`     |
  </Accordion>

  <Accordion title="set_app_config">
    Write an app's `deploy` or `ai` config section (admin/owner-scoped).

    | Parameter         | Type          | Required | Default |
    | ----------------- | ------------- | -------- | ------- |
    | `name`            | `string`      | Yes      | `—`     |
    | `section`         | `string`      | Yes      | `—`     |
    | `values`          | `object`      | Yes      | `—`     |
    | `dry_run`         | `boolean`     | No       | `false` |
    | `restart`         | `boolean`     | No       | `false` |
    | `if_match`        | `string/null` | No       | `null`  |
    | `idempotency_key` | `string/null` | No       | `null`  |
  </Accordion>

  <Accordion title="set_config">
    Write a daemon config section (admin-scoped, validated, audited).

    | Parameter         | Type          | Required | Default |
    | ----------------- | ------------- | -------- | ------- |
    | `section`         | `string`      | Yes      | `—`     |
    | `values`          | `object`      | Yes      | `—`     |
    | `dry_run`         | `boolean`     | No       | `false` |
    | `if_match`        | `string/null` | No       | `null`  |
    | `idempotency_key` | `string/null` | No       | `null`  |
  </Accordion>

  <Accordion title="set_secret">
    Set/merge write-only secrets for a service; returns key names only.

    | Parameter         | Type          | Required | Default |
    | ----------------- | ------------- | -------- | ------- |
    | `service`         | `string`      | Yes      | `—`     |
    | `values`          | `object`      | Yes      | `—`     |
    | `idempotency_key` | `string/null` | No       | `null`  |
  </Accordion>

  <Accordion title="share_service">
    Use when: you need a URL you can open (public\_url is LAN-only).

    | Parameter         | Type          | Required | Default     |
    | ----------------- | ------------- | -------- | ----------- |
    | `name`            | `string`      | Yes      | `—`         |
    | `access`          | `string`      | No       | `"private"` |
    | `consent`         | `boolean`     | No       | `false`     |
    | `idempotency_key` | `string/null` | No       | `null`      |
  </Accordion>

  <Accordion title="stop_service">
    Stop a service (desired\_state → stopped).

    | Parameter         | Type          | Required | Default |
    | ----------------- | ------------- | -------- | ------- |
    | `name`            | `string`      | Yes      | `—`     |
    | `idempotency_key` | `string/null` | No       | `null`  |
  </Accordion>

  <Accordion title="system_disk">
    Report disk usage: docker totals + named-volume/model/archive/backup trees.

    No parameters.
  </Accordion>

  <Accordion title="system_gc">
    Garbage-collect orphan app images (admin-scoped, audited).

    | Parameter             | Type          | Required | Default |
    | --------------------- | ------------- | -------- | ------- |
    | `include_orphan_data` | `boolean`     | No       | `false` |
    | `dry_run`             | `boolean`     | No       | `false` |
    | `idempotency_key`     | `string/null` | No       | `null`  |
  </Accordion>

  <Accordion title="unshare_service">
    Use when: an app should stop being reachable at its hosted URL.

    | Parameter         | Type          | Required | Default |
    | ----------------- | ------------- | -------- | ------- |
    | `name`            | `string`      | Yes      | `—`     |
    | `idempotency_key` | `string/null` | No       | `null`  |
  </Accordion>

  <Accordion title="wait_for_service">
    Use when: a deploy is in flight and you need its real outcome.

    | Parameter | Type           | Required | Default |
    | --------- | -------------- | -------- | ------- |
    | `name`    | `string`       | Yes      | `—`     |
    | `version` | `integer/null` | No       | `null`  |
    | `timeout` | `integer`      | No       | `60`    |
  </Accordion>

  <Accordion title="write_app_files">
    Write files into an app's server-side workspace, then deploy it.

    | Parameter         | Type          | Required | Default |
    | ----------------- | ------------- | -------- | ------- |
    | `name`            | `string`      | Yes      | `—`     |
    | `files`           | `object`      | Yes      | `—`     |
    | `delete`          | `array/null`  | No       | `null`  |
    | `idempotency_key` | `string/null` | No       | `null`  |
  </Accordion>
</AccordionGroup>