MCP setup and tool reference

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. 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:

{
  "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. 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:

[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 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

Call capabilities and doctor to learn the node’s current abilities and the caller’s permissions.
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.
Use dry_run=true where supported, inspect the plan, then submit the real deployment.
Call wait_for_service with its name and returned deployment version. Inspect diagnose_service on failure and service_logs for selected output.
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.

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 before reusing one. restart_daemon can close its own HTTP connection during a successful restart: check health before treating that as failure.

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.

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 or HTTP API and the recovery guide for those operator actions.

Tool reference

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`

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`

capabilities

Describe this daemon: version, caller role/quotas, URL grammar, backends.No parameters.

cluster_stats

Get aggregate cluster metrics (GPUs in use/total, services up).No parameters.

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`

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`

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`

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`

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`

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`

doctor

Run the daemon’s bounded environment health checks (docker/gpu/proxy/db/…).No parameters.

dump_database

Capture a logical, application-consistent dump of a managed database.

Parameter	Type	Required	Default
`name`	`string`	Yes	`—`
`timeout_s`	`integer`	No	`300`

get_app_config

Read a deployed app’s daemon-persisted config (deploy fields + ai bindings).

Parameter	Type	Required	Default
`name`	`string`	Yes	`—`

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`

get_config

Read daemon config: one section view, or all sections when omitted.

Parameter	Type	Required	Default
`section`	`string/null`	No	`null`

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`

get_service

Get one service. name accepts the service name or the job id.

Parameter	Type	Required	Default
`name`	`string`	Yes	`—`

list_app_files

List an app’s workspace: paths, sizes, sha256 and totals.

Parameter	Type	Required	Default
`name`	`string`	Yes	`—`

list_app_templates

List the app template store — deployable starter apps (id/name/coordinates).No parameters.

list_database_dumps

List the dump tars this daemon holds for one managed database.

Parameter	Type	Required	Default
`name`	`string`	Yes	`—`

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`

list_gpus

List GPUs known to the daemon, with live utilization metrics.No parameters.

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`

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`

list_secret_names

List a service’s secret key names (values are never returned).

Parameter	Type	Required	Default
`service`	`string`	Yes	`—`

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`

proxy_status

Get the embedded proxy’s typed state (TLS, apex, respawn, live routes).No parameters.

read_app_file

Read one file back from an app’s workspace as text.

Parameter	Type	Required	Default
`name`	`string`	Yes	`—`
`path`	`string`	Yes	`—`

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`

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`

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`

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`

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`

restart_service

Restart a service (clears backoff).

Parameter	Type	Required	Default
`name`	`string`	Yes	`—`
`idempotency_key`	`string/null`	No	`null`

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`

serve

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`

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`

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"`

service_stats

Get live CPU, memory, network and PID usage for a running service.

Parameter	Type	Required	Default
`name`	`string`	Yes	`—`

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`

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`

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`

stop_service

Stop a service (desired_state → stopped).

Parameter	Type	Required	Default
`name`	`string`	Yes	`—`
`idempotency_key`	`string/null`	No	`null`

system_disk

Report disk usage: docker totals + named-volume/model/archive/backup trees.No parameters.

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`

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`

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`

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`

Start here

Build and operate

Access and interfaces

HTTP endpoints

Get help

MCP setup and tool reference

Connect over stdio

Connect over HTTP

Deploy from an agent

Safe operation

Tool reference

​Connect over stdio

​Connect over HTTP

​Deploy from an agent

​Safe operation

​Tool reference

Connect over stdio

Connect over HTTP

Deploy from an agent

Safe operation

Tool reference