Use it from an AI agent

The CLI ships an MCP server. Point an agent at it and it can list your projects, create services, trigger and inspect deploys, pull build logs, attach domains and set environment variables.

5 min read

Register with Claude Code

Terminal

bash

naijacloud login
claude mcp add --transport stdio naijacloud -- naijacloud mcp

No token goes into the MCP config. The server reads the credentials naijacloud login already stored. To scope a server to a different account, add --env HOSTING_API_TOKEN=<token>.

If you installed from source and naijacloud is not on your PATH, register the absolute path to the built entrypoint:

Terminal

bash

claude mcp add --transport stdio naijacloud -- node /absolute/path/to/nc-cli/build/cli.js mcp

Register with Claude Desktop

Add this to claude_desktop_config.json:

claude_desktop_config.json

json

{
  "mcpServers": {
    "naijacloud": {
      "command": "naijacloud",
      "args": ["mcp"]
    }
  }
}

Test it by hand

Terminal

bash

npx @modelcontextprotocol/inspector naijacloud mcp

The Inspector opens a browser UI where you can list the tools and call them one at a time. It is the quickest way to confirm the server works before wiring it into an agent.

Tools

Tool	Parameters	Notes
`list_projects`		Every project across all your teams. Read-only
`get_project`	`projectId`	Project, its environments, and the services in each. This is how you get a `serviceId`. Read-only
`list_deployments`	`serviceId` or `projectId`	Exactly one. `projectId` fans out across the project's services. Read-only
`get_deployment`	`deploymentId`	Status, branch, commit and failure reason. Read-only
`create_deployment`	`serviceId`, `branch?`, `commit?`	Triggers a build and release
`delete_deployment`	`deploymentId`, `confirm`	Cancels an in-flight build. Requires `confirm: true`
`get_deployment_logs`	`deploymentId`, `limit?`	Build and runtime lines. Read-only
`list_domains`	`serviceId` or `projectId`	Custom domains and the DNS records they need. Read-only
`add_domain`	`serviceId`, `domain`	Attaches a domain. Returns the DNS `records` to create for the service's region, and any `conflicts` to remove
`create_service`	`environmentId`, `name`, one of `repoFullName`, `gitUrl` or `image`, `type?`, `confirm`	Creates a web service or cron job at the Free size unless `tier` names a paid one, and queues its first build. Requires `confirm: true`
`list_env_vars`	`serviceId` or `projectId`	Values always masked. Read-only
`set_env_var`	`serviceId`, `key`, `value`, `target?`, `secret?`, `confirm`	Upserts one variable. Requires `confirm: true`

The MCP surface is deliberately narrower than the CLI's. Static deploys read and write your local filesystem, and the database console runs write-capable SQL whose guardrail is a terminal prompt. Neither survives translation into a tool call an agent makes on its own, so deploy, init and db stay CLI-only.

Safety behaviour

delete_deployment, create_service and set_env_var are confirm-gated. Without confirm: true they return an error and do nothing, so an agent has to come back deliberately after checking with you.
Values are never echoed. list_env_vars replaces every value with ******** and reports only its length. set_env_var does not include the value it wrote in its response.
Tokens are never logged. Not in tool output, not in error messages, not in diagnostics.
stdout is protocol only. Under naijacloud mcp every diagnostic goes to stderr, so nothing can corrupt the MCP stream.
Errors are short and typed. API failures surface as a status code plus the platform's message, never a stack trace.

Three things worth knowing

The hierarchy is team, project, environment, service, deployment. Deployments, domains and environment variables belong to a service, not to a project. That is why most tools take a serviceId, with projectId accepted as a convenience that fans out. get_project is the discovery hop that turns a project into service ids.

delete_deployment cancels, it does not delete. Deployment history is immutable. The tool stops an in-flight build, which only works while it is queued, building, testing or deploying. It does not roll back a live release; naijacloud rollback <deployment-id> does that from the CLI.

create_deployment cannot pick a branch or commit. A deploy builds the tip of the branch configured on the service. The branch parameter is treated as an assertion, checked against the service's configured branch and rejected on a mismatch, and commit is rejected outright. Both fail loudly rather than silently deploying something other than what was asked for.

Preview versus production is a property of the service, not a flag.

A service lives in an environment, so deploying a service in prod is a production deploy. The response reports the environment name and whether it is a preview environment. Check it.

Environment variable scopes

`target`	Naijacloud scope
`production`	`PROD`
`preview`	`UAT`, the pre-production scope. There is no `PREVIEW`
`development`	`DEV`
`all`	`ALL`

Leave target out and the variable is written at the scope the service's environment reads: DEV in an environment called dev, UAT in uat or a preview, PROD in prod. Do not pass production for a service in a dev environment. A dev environment never reads PROD variables, so the write would succeed and the app would never see it.

Setting a variable upserts by key and leaves the service's others untouched. The response reports needsRedeploy when the service has to be redeployed for the change to take effect.

Next steps

Environment variablesScopes, secrets and secret files.