---
title: MCP tools
description: Every tool the Dekka MCP server offers, the scope each one needs, and its arguments.
section: Agents
order: 3
updated: 2026-11-04
---

A key sees the tools its scopes allow. **Read** tools look at things and change nothing, **write** tools create and change things, and **admin** tools delete things or reveal credentials. A key with write also sees the read tools, and a key with admin sees them all. Ids come from earlier calls, so an agent usually starts with `whoami`, then `list_projects` and `get_project`.

## Account and projects

| Tool | Scope | Arguments | What it does |
| --- | --- | --- | --- |
| `whoami` | read | | The person the key acts for, the organisation, the key's scopes, and the plan's limits and usage |
| `list_projects` | read | | Every project with its environments and service count |
| `get_project` | read | `project_id` | Environments, services and databases with status and URLs, and the connections between them |
| `create_project` | write | `name`, `description`, `region_id` | A new project with a production environment |

## Services

| Tool | Scope | Arguments | What it does |
| --- | --- | --- | --- |
| `list_services` | read | `project_id`, `environment_id` | Services and databases with status, URL and source |
| `get_service` | read | `service_id` | Status, URL, every setting and the three latest deployments |
| `create_service` | write | `project_id`, `name`, `repo` or `image`, `branch`, `root_dir`, `kind`, `port`, `start_command`, `cron_schedule`, `environment_id` | A service from a GitHub repository or a Docker image, deployed straight away |
| `update_service` | write | `service_id`, `settings`, `name` | Merges the settings given into the current ones; they apply on the next deploy |
| `restart_service` | write | `service_id`, `action` | Restarts, stops or starts a service |
| `delete_service` | admin | `service_id`, `confirm` | Deletes a service or database with everything in it |

`kind` is `application` for a service that answers HTTP on a port, `worker` for one that runs in the background, or `scheduled_job` for one that runs on `cron_schedule`, a five-field cron in UTC. `settings` uses the groups `get_service` shows, so `{"runtime": {"memory_mib": 512}}` changes the memory and leaves everything else alone.

## Deploys

| Tool | Scope | Arguments | What it does |
| --- | --- | --- | --- |
| `deploy` | write | `service_id`, `branch`, `commit_sha` | Builds the branch head or the given commit, or pulls an image again |
| `list_deployments` | read | `service_id` or `project_id`, `limit` | Recent deployments, newest first |
| `get_deployment` | read | `deployment_id` | Status, commit, image, timings, error and the settings it deployed |
| `get_deploy_logs` | read | `deployment_id`, `tail`, `errors_only` | The build and deploy log, with lines that look like errors marked |
| `rollback` | write | `deployment_id`, `confirm` | Redeploys the image an earlier deployment built |

## Data and variables

| Tool | Scope | Arguments | What it does |
| --- | --- | --- | --- |
| `add_database` | write | `project_id`, `kind`, `name`, `connect_to`, `environment_id` | PostgreSQL, Redis, a bucket or a queue, optionally connected to services |
| `connect_services` | write | `service_id`, `database_id` | Connects a service, which gets variables such as `DATABASE_URL` on its next deploy |
| `get_connection_strings` | admin | `database_id`, `reveal` | Each connected service's URL, masked unless `reveal` is true |
| `list_variables` | read | `service_id` or `environment_id` | Variables with secret values hidden |
| `set_variables` | write | `variables`, `service_id` or `environment_id`, `secret` | Creates or updates variables and leaves the rest alone |
| `delete_variable` | admin | `key`, `service_id` or `environment_id`, `confirm` | Deletes one variable |

Values passed to `set_variables` can use [references](/docs/environment-variables), such as `${{api.DEKKA_PRIVATE_DOMAIN}}` or `${{shared.STRIPE_KEY}}`. Each reveal of a connection string is recorded in the activity log.

## Templates and changes

| Tool | Scope | Arguments | What it does |
| --- | --- | --- | --- |
| `list_templates` | read | `category` | Templates with what each creates and the inputs it needs |
| `get_template` | read | `template_id`, `include_yaml` | One template's services, volumes, inputs and generated secrets |
| `plan_template` | write | `environment_id`, `template_id`, `inputs` | Plans a template and returns the changes |
| `plan_blueprint` | write | `environment_id`, `content`, `inputs`, `prune` | Plans a [dekka.yaml](/docs/config-as-code), with every validation error and its path |
| `plan_compose` | write | `environment_id`, `content`, `inputs`, `repository`, `branch` | Translates a [Docker Compose file](/docs/docker-compose) and plans it, with a report of what was adjusted |
| `get_pending_changes` | read | `environment_id` | Changesets waiting to be applied |
| `apply_changes` | write | `changeset_id`, `confirm` | Applies every change in a changeset |
| `discard_changes` | write | `changeset_id` | Throws a changeset away |

Plans change nothing. `apply_changes` without `confirm` returns the same list of changes, which is what an agent should show you before confirming.

## Domains

| Tool | Scope | Arguments | What it does |
| --- | --- | --- | --- |
| `add_domain` | write | `service_id`, `hostname` | Adds a custom domain and returns the CNAME and TXT records to create |
| `verify_domain` | write | `domain_id` | Checks the records, and the domain goes active once the TXT record matches |

## Logs, metrics and operations

| Tool | Scope | Arguments | What it does |
| --- | --- | --- | --- |
| `search_logs` | read | `project_id`, `query`, `service_id`, `stream`, `since_minutes`, `limit` | Searches build, deploy and runtime logs across a project |
| `get_runtime_logs` | read | `service_id`, `tail` | The latest lines a running service wrote |
| `get_metrics` | read | `service_id`, `window` | CPU, memory, network, disk, requests and p95 latency as latest, average and peak |
| `get_operation` | read | `operation_id` | The state and progress of a long-running operation |

## Docs

| Tool | Scope | Arguments | What it does |
| --- | --- | --- | --- |
| `search_docs` | read | `query` | Finds docs pages about a topic |
| `read_doc` | read | `slug` | One docs page as Markdown |

## Resources and prompts

Each docs page is also a resource at `dekka://docs/<slug>`, such as `dekka://docs/connections`. The server offers three prompts, which clients usually show as slash commands.

| Prompt | Arguments | What it asks the agent to do |
| --- | --- | --- |
| `deploy_repo` | `repo`, `project` | Deploy a GitHub repository, follow the build and report the URL |
| `add_database` | `service`, `kind` | Add a database to a service's project, connect it and redeploy |
| `debug_deploy` | `service` | Find out why the latest deployment failed and suggest a fix without changing anything |

## Errors

When the API refuses something, the tool returns its message with the status and code, such as `The Free plan includes 1 project. (403 entitlement_exceeded)`. A 404 can mean the thing doesn't exist or that the key can't reach it, since a [project token](/docs/project-tokens) sees only its own project.