Use it from an AI agent · Naijacloud docs

CLI

Use it from an AI agent

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

5 min read

Register with Claude Code

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:

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

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

Test it by hand

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 target
`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 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.

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` (default)	`PROD`
`preview`	`UAT`, the pre-production scope. There is no `PREVIEW`
`development`	`DEV`
`all`	`ALL`

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

Command reference →

Everything the CLI does, including what MCP leaves out.

Environment variables →

Scopes, secrets and secret files.

← Previous

Command reference

Deploy a web service