NEXUSRUN

# NEXUS AI MCP Server Reference The NEXUS AI MCP server exposes the full deployment platform as Model Context Protocol tools. Connect it to Claude Desktop, Claude Code, Cursor, Codex CLI, or any MCP-compatible client and your AI agent can deploy applications, attach databases and storage, run backups, restore data, query schemas, and roll back releases on your behalf. **Endpoint:** `https://nexusai.run/mcp` **Transport:** HTTPS with Bearer-token authentication **Tools:** 59 tools across 9 categories **Audit:** every action is recorded with actor identity and timestamp This document is the canonical reference for every tool the server exposes. For tutorials and recipes see the blog posts under [/blog/category/ai-deployments](https://nexusai.run/blog). --- ## Quick start ### Claude Desktop Add this block to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows): ```json { "mcpServers": { "nexus-ai": { "url": "https://nexusai.run/mcp", "headers": { "Authorization": "Bearer <your-nexus-token>" } } } } ``` Restart Claude Desktop. The 59 NEXUS AI tools appear in the tool list, prefixed `nexusai_*`. ### Cursor Cursor Settings, MCP, Add server. Use the same URL and Bearer token. ### Claude Code ```bash claude mcp add nexus-ai --url https://nexusai.run/mcp --header "Authorization: Bearer <your-nexus-token>" ``` ### Codex CLI Add to `~/.config/codex/config.toml` (or wherever your Codex install reads MCP config): ```toml [mcp.servers.nexus-ai] url = "https://nexusai.run/mcp" headers = { Authorization = "Bearer <your-nexus-token>" } ``` ### Generic MCP client Any client that speaks MCP over HTTP works. Point it at `https://nexusai.run/mcp` and attach a Bearer token. --- ## Authentication Generate a token at `https://nexusai.run/app/tokens`. **Scopes:** | Scope | Grants | | ---------------------- | --------------------------------------------------------------------- | | `deployments:read` | List, status, logs, health of deployments | | `deployments:create` | Create, deploy, scale, restart, redeploy, attach storage | | `deployments:delete` | Stop, start, delete deployments and their resources | | `secrets:read` | List secrets (metadata only, never values) | | `secrets:manage` | Create, update, delete secrets | | `db:read` | List DB sources, inspect schemas, list backups | | `db:query` | Run sandboxed SELECT queries on connected DB sources | | `db:admin` | DML / DDL queries, propose and apply fixes, restore from backup | | `volumes:read` | List org-scoped volumes | | `volumes:manage` | Create, delete, attach, detach volumes | | `buckets:read` | List buckets, list bucket files | | `buckets:manage` | Create, delete, attach, detach, rotate credentials, upload/download | | `domains:read` | List custom domains | | `domains:manage` | Add, verify, remove custom domains | | `support:read` | List and read support tickets | | `support:write` | Create tickets, reply to threads | Start your agent with the minimum scope set it needs. Tokens are independently revocable from the dashboard. Every tool call is logged with the token's name in the audit trail, so you can attribute changes to specific agents (`claude-prod`, `cursor-staging`). --- ## Tool reference ### Identity and discovery (4 tools) | Tool | Description | Scope | | -------------------------- | ------------------------------------------------------------------------------------ | ------------------ | | `nexusai_whoami` | Returns the authenticated user and tenant context. | none (auth only) | | `nexusai_projects_list` | Lists projects available in the current tenant. | `deployments:read` | | `nexusai_providers_list` | Lists deployment providers allowed for the tenant plan. | `deployments:read` | | `nexusai_usage_stats` | Returns usage statistics, quotas, and deployment counts for the organization. | `deployments:read` | --- ### Deployments (14 tools) | Tool | Description | Scope | | ----------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------- | | `nexusai_deploy_list` | Lists deployments. Filter by status (queued/deploying/running/failed/terminated) and provider. | `deployments:read` | | `nexusai_deploy_status` | Status details for one deployment (state, health, replicas, URL). | `deployments:read` | | `nexusai_deploy_health` | Health check status and recent health-check log lines for a deployment. | `deployments:read` | | `nexusai_deploy_logs` | Recent log lines for a deployment. Set `type` to `build` or `runtime` (default). | `deployments:read` | | `nexusai_deploy_create` | Deploy from a container image (Docker Hub, ECR, GCR, ACR, custom registry). | `deployments:create` | | `nexusai_deploy_source` | Deploy from a Git repository. Supports services (postgres/redis/mongo/mysql), workers, env vars. | `deployments:create` | | `nexusai_deploy_openclaw` | One-call deploy of an OpenClaw gateway service (Claude Code-compatible AI coding assistant). | `deployments:create` | | `nexusai_deploy_flixty` | One-call deploy of Flixty (self-hosted social media studio for X/LinkedIn/Facebook/Instagram/etc). | `deployments:create` | | `nexusai_deploy_redeploy` | Create a new deployment using a previous deployment configuration with optional overrides. | `deployments:create` | | `nexusai_deploy_rollback` | Roll back to a previous deployment revision in the same project. | `deployments:create` | | `nexusai_deploy_start` | Start a stopped deployment (soft start, preserves attached storage and DB services). | `deployments:create` | | `nexusai_deploy_stop` | Stop a running deployment without deleting it (soft stop, data preserved). | `deployments:create` | | `nexusai_deploy_scale` | Scale a running deployment to 1-10 replicas. | `deployments:create` | | `nexusai_deploy_delete` | Permanently delete a deployment and free its resources. Destructive. | `deployments:delete` | Supported deployment providers: `docker` (NEXUS AI managed Container platform, full-stack), `gcp_cloud_run`, `aws_ecs_fargate`, `azure_container_apps` (cloud providers, single-container only). --- ### Secrets (4 tools) | Tool | Description | Scope | | --------------------------- | ---------------------------------------------------------------------- | ----------------- | | `nexusai_secrets_list` | List all secrets for the organization. Values are never returned. | `secrets:read` | | `nexusai_secrets_create` | Create a new secret. Encrypted at rest with AES-256-GCM. | `secrets:manage` | | `nexusai_secrets_update` | Update an existing secret. Only provided fields change. | `secrets:manage` | | `nexusai_secrets_delete` | Delete a secret from the organization. | `secrets:manage` | Secrets are injected as environment variables at container start. They are never logged, never written to images, and never returned over the API. --- ### Custom domains (4 tools) | Tool | Description | Scope | | --------------------------- | --------------------------------------------------------------------------- | ----------------- | | `nexusai_domains_list` | List custom domains attached to a deployment. | `domains:read` | | `nexusai_domains_add` | Add a custom domain to a deployment. Returns DNS records to configure. | `domains:manage` | | `nexusai_domains_verify` | Trigger DNS verification for a custom domain. | `domains:manage` | | `nexusai_domains_remove` | Remove a custom domain from a deployment. | `domains:manage` | Verified domains automatically receive Let's Encrypt certificates via the platform's Traefik ingress. --- ### External database sources / DB intelligence (8 tools) For querying and managing external databases connected by the user (separate from the databases provisioned with a deployment). | Tool | Description | Scope | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | | `nexusai_db_source_list` | List all external DB sources connected to the organization. | `db:read` | | `nexusai_db_source_connect` | Create and test a new external DB connection. Credentials encrypted at rest. | `db:admin` | | `nexusai_db_source_delete` | Remove an external DB source from the organization. | `db:admin` | | `nexusai_db_inspect_schema` | Get the normalized schema graph (tables, columns, types, constraints, indexes) for a DB source. Cached for 5 minutes; `refresh: true` forces a re-pull. | `db:read` | | `nexusai_db_query_preview` | Dry-run a SQL query. Returns the `EXPLAIN` plan plus a safety analysis. Supports SELECT, DML, and DDL including `CREATE/DROP FUNCTION`, `CREATE/DROP TRIGGER`, `CREATE/DROP VIEW`, `CREATE/DROP PROCEDURE`. | `db:read` | | `nexusai_db_query_execute` | Execute a confirmed SQL statement against an external DB source. SELECT runs sandboxed. DML and DDL require `confirmed: true`. Function/procedure bodies with dollar-quoting (`$$...$$`) supported. | `db:query` / `db:admin` | | `nexusai_db_propose_fix` | Analyze deployment log errors and propose a DDL fix. The AI reads the log snippet, infers the schema gap, and returns a proposed DDL change for review. | `db:admin` | | `nexusai_db_apply_fix` | Apply a previously proposed DDL fix (requires the proposal ID returned by `nexusai_db_propose_fix`). Logged in the audit trail. | `db:admin` | Query execution runs in a sandboxed session with a statement timeout and a row-count cap. The fix proposal flow gives you a review step before any DDL changes land on a real database. --- ### Deployment-managed databases / backups (7 tools) For databases (Postgres, MySQL, Mongo, Redis) provisioned as services alongside a deployment. | Tool | Description | Scope | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | | `nexusai_db_services_list` | List all database services provisioned alongside deployments. Use this to discover the `serviceId` required by backup, restore, and schedule tools. Filter by `deploymentId` to scope to one deployment. | `deployments:read` | | `nexusai_db_backup` | Create a backup of a database service in a Docker deployment (pg_dump for Postgres, mysqldump for MySQL, mongodump for Mongo, BGSAVE for Redis). | `db:admin` | | `nexusai_db_backup_list` | List available backups for a database service, with size and timestamps. | `db:read` | | `nexusai_db_backup_download` | Generate a short-lived signed download URL (30-3600s TTL, default 300s) for a backup file. Backups are portable: pg_dump custom format, mysqldump SQL, mongodump tar.gz, Redis rdb. No data lock-in. | `db:read` | | `nexusai_db_restore` | Restore a database service from a previously created backup. Existing data is overwritten. Destructive. | `db:admin` | | `nexusai_db_restore_to` | Restore a backup INTO a different deployment service in the same org. Use to seed a new deployment from a snapshot of an old one. Both services must use the same engine (postgres-to-postgres only). | `db:admin` | | `nexusai_db_backup_schedule` | Enable or disable daily automated backups for a database service. | `db:admin` | --- ### Persistent storage volumes (5 tools) Org-scoped filesystem mounts. Each volume is single-attach and survives redeploys. | Tool | Description | Scope | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | | `nexusai_volume_list` | List org-scoped persistent storage volumes. | `volumes:read` | | `nexusai_volume_create` | Create a new volume. Backed by a Docker named volume that survives redeploys. Slug-style name, 1-32 chars, lowercase + digits + `-`. | `volumes:manage` | | `nexusai_volume_attach` | Attach a volume to a deployment at a mount path (default `/data`). **Requires a redeploy of the target deployment** to take effect. | `volumes:manage` | | `nexusai_volume_detach` | Detach the volume from its current deployment. Data is preserved. | `volumes:manage` | | `nexusai_volume_delete` | Delete a volume. Must be detached first. Destroys all data on the volume. Destructive. | `volumes:manage` | --- ### S3-compatible buckets (9 tools) Multi-attach object storage on the platform's MinIO instance. Each bucket ships with a scoped per-bucket IAM service account. | Tool | Description | Scope | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | | `nexusai_bucket_list` | List org-scoped object-storage buckets. | `buckets:read` | | `nexusai_bucket_create` | Create a new bucket on the shared MinIO instance. Slug 3-63 lowercase chars. Region defaults to `us-east-1`. A fresh per-bucket MinIO service account is provisioned with an inline IAM policy scoped to this bucket only. | `buckets:manage` | | `nexusai_bucket_attach` | Expose the bucket to a deployment via S3-style env vars (`S3_ENDPOINT`, `S3_BUCKET`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, `S3_REGION`, plus per-bucket `S3_BUCKET_<UPPER>_*`). **Requires a redeploy** of the target deployment for env vars to inject. | `buckets:manage` | | `nexusai_bucket_detach` | Remove the bucket from a deployment. S3 env vars stop being injected on next deploy. | `buckets:manage` | | `nexusai_bucket_rotate_credentials` | Generate fresh per-bucket MinIO service-account credentials, replacing the previous ones. Use to migrate legacy buckets (shared root creds) to scoped IAM, or to respond to a credential leak. Attached deployments must be redeployed. | `buckets:manage` | | `nexusai_bucket_files_list` | List objects in a bucket, optionally filtered by key prefix. Limit 1-1000, default 1000. | `buckets:read` | | `nexusai_bucket_file_download` | Issue a short-lived signed URL (30-3600s TTL, default 300s) to download a file from a bucket without an API token. The URL itself is the bearer; share with caution. | `buckets:read` | | `nexusai_bucket_file_delete` | Delete a single file from a bucket. | `buckets:manage` | | `nexusai_bucket_delete` | Delete a bucket. Must be detached from all deployments first. ALL objects in the bucket are deleted. Destructive. | `buckets:manage` | --- ### Support (4 tools) | Tool | Description | Scope | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | `nexusai_support_ticket_create` | Submit a new support ticket. Priority `LOW`/`MEDIUM`/`HIGH`/`URGENT`. Category `general`/`billing`/`technical`/`deployment`/`database`. | `support:write` | | `nexusai_support_ticket_list` | List your organization's support tickets. Filter by status (`OPEN`/`IN_PROGRESS`/`RESOLVED`/`CLOSED`). Paginated. | `support:read` | | `nexusai_support_ticket_get` | Get the full details and message thread for a support ticket. | `support:read` | | `nexusai_support_ticket_reply` | Add a reply message to an existing support ticket. | `support:write` | --- ## Common workflows ### Deploy a full-stack app from a prompt The agent calls in order: ``` 1. nexusai_projects_list # find target project 2. nexusai_deploy_source # build from repo with services=[postgresql, redis] 3. nexusai_bucket_create # provision a bucket for uploads 4. nexusai_bucket_attach # wire bucket env vars into the deploy 5. nexusai_deploy_redeploy # apply the bucket attachment 6. nexusai_deploy_status # confirm RUNNING ``` ### Snapshot, migrate, validate, recover The right ops pattern for a risky schema change: ``` 1. nexusai_db_services_list # discover postgres service id 2. nexusai_db_backup # snapshot first 3. <agent runs your migration> 4. nexusai_deploy_logs # check for errors 5a. (success) nexusai_db_backup_list # confirm backup is on the retention list 5b. (failure) nexusai_db_restore # restore from the snapshot nexusai_deploy_rollback # revert to the previous release image ``` ### Migrate a legacy bucket to scoped IAM For buckets created before the per-bucket service-account model (when shared root credentials were in use): ``` 1. nexusai_bucket_rotate_credentials # generates fresh scoped svcacct creds 2. nexusai_deploy_redeploy # for each deployment attached to the bucket 3. nexusai_deploy_status # confirm RUNNING with new S3_* vars ``` ### Seed a staging environment from production ``` 1. nexusai_db_services_list # find prod postgres serviceId 2. nexusai_db_backup # take a fresh snapshot 3. nexusai_db_services_list # find staging postgres serviceId 4. nexusai_db_restore_to # restore prod backup INTO staging ``` ### Diagnose and fix a failing deploy ``` 1. nexusai_deploy_status # state, health, restart count 2. nexusai_deploy_logs # last 200 lines of runtime logs <agent identifies the error> 3a. nexusai_secrets_create / nexusai_secrets_update # if missing env var 3b. nexusai_db_propose_fix → nexusai_db_apply_fix # if schema gap 3c. <agent edits code in IDE, pushes, triggers nexusai_deploy_redeploy> 4. nexusai_deploy_logs # confirm fix ``` --- ## Safety model ### Confirmation gates These tools require explicit user confirmation in the same conversation turn. The agent will pause and ask before calling them: - `nexusai_deploy_delete` (permanent) - `nexusai_db_query_execute` with DML/DDL (requires `confirmed: true`) - `nexusai_db_apply_fix` (requires the proposal ID + an explicit go-ahead) - `nexusai_db_restore` (overwrites existing data) - `nexusai_db_restore_to` (overwrites target deployment's data) - `nexusai_bucket_delete` (deletes all bucket contents) - `nexusai_bucket_rotate_credentials` (invalidates current keys) - `nexusai_volume_delete` (destroys all volume data) A well-configured agent system prompt should reinforce these gates ("never call delete tools without an explicit 'yes, delete <resource>' from the user in the same message"). ### Audit log Every tool call writes an entry to the `AuditLog` table with: - Actor identity (user ID + token name) - Tool name - Input parameters (sensitive values redacted) - Result (success / failure + error if any) - Timestamp + IP address + user agent Exportable from the dashboard for SOC 2 / HIPAA reviews. Search by token name, action, resource ID, or time range. ### Token scopes Tokens are independently scoped (see [Authentication](#authentication)). Start your agent read-only, promote scopes only when the workflow demands it. Tokens can be revoked instantly from the dashboard; revocation takes effect within seconds. ### Rate limits Standard API rate limits apply per token. Heavy reconciliation loops should batch using the `*_list` tools' pagination instead of polling individual resources. ### Data ownership - Code lives in your Git repository (NEXUS AI never stores source long-term). - Secrets live encrypted in your NEXUS AI organization (AES-256-GCM, never returned over the API). - Database data lives on persistent volumes attached to your deployment. - Bucket data lives on the platform's MinIO instance under a scoped per-bucket service account. - Backups are downloadable via `nexusai_db_backup_download` in portable formats (pg_dump, mysqldump, mongodump, Redis rdb). No vendor lock-in. --- ## Troubleshooting **`nexusai_whoami` returns 401 Unauthorized** Token is invalid or revoked. Generate a fresh token at `https://nexusai.run/app/tokens` and update your MCP client config. **`nexusai_deploy_create` returns 403** The token does not have `deployments:create` scope. Add it via the dashboard. **`nexusai_db_query_execute` fails with "DML requires confirmation"** Add `"confirmed": true` to the call. The agent should surface the proposed SQL to the user first via `nexusai_db_query_preview` and only set `confirmed: true` after explicit approval. **Bucket env vars not visible to the app after `nexusai_bucket_attach`** Bucket attachments are baked into the compose YAML at deploy time. Call `nexusai_deploy_redeploy` to apply. **Volume mount path is empty after `nexusai_volume_attach`** Same root cause. Volume mounts are baked at deploy time. Call `nexusai_deploy_redeploy`. **`nexusai_db_restore_to` fails with "engine mismatch"** You are trying to restore (for example) a Postgres backup into a MySQL service. Cross-engine restores are not supported; both services must run the same engine. **Tool call times out** Long-running operations (full deploys, backups of large databases, restores) can exceed standard MCP timeouts. The platform's actual operation continues in the background. Use `nexusai_deploy_status` or `nexusai_db_backup_list` to check completion. --- ## FAQ **Which MCP clients are supported?** Claude Desktop, Claude Code, Cursor, Codex CLI, Windsurf, Zed AI, and any client that speaks MCP over HTTPS with a Bearer-token Authorization header. **Is there a public MCP registry entry?** NEXUS AI is listed in the community MCP server registries. To add the server in one click from your client's marketplace UI, search for "NEXUS AI" or "nexus-ai". **Can two agents share one organization?** Yes. Each agent uses its own token. Audit log entries record which token took each action. **Does the agent ever see secret values?** No. `nexusai_secrets_list` returns names and metadata only. `nexusai_secrets_create` accepts values you provide. The platform never returns decrypted secret values over the API or MCP. **Can the agent operate without me being online?** Yes. The MCP server accepts calls 24/7. Agents acting on a scheduled trigger (cron, GitHub Action) can call the same tools. **What happens if a tool call fails halfway through a workflow?** Each tool call is atomic. Most platform actions are reversible (stops have starts, deploys have rollbacks, backups have restores). The audit log records each step so you can resume from the last successful action. **How do I report a bug in an MCP tool?** Open a support ticket via `nexusai_support_ticket_create` with category `technical`, or email `[email protected]`. Include the tool name, input parameters, and the error response. --- ## Versioning - Tool names follow `nexusai_<area>_<verb>` and are stable across releases. - New tools are added in additive releases. - Breaking changes to existing tools (parameter renames, semantic changes) are announced in the changelog at `https://nexusai.run/blog/category/changelog` with at least 30 days notice. --- ## Related reading - [Your AI app is generated. Now how do you deploy it?](https://nexusai.run/blog/your-ai-app-is-generated-now-how-do-you-deploy-it). The deploy gap for AI-generated apps and how NEXUS AI closes it. - [MCP-driven deploys: 5 tasks your Claude agent should be running for you](https://nexusai.run/blog/mcp-driven-deploys-5-tasks-your-claude-agent-should-run). Concrete operations to hand to an agent today. - [How NEXUS AI keeps your Postgres alive across host reboots](https://nexusai.run/blog/how-nexus-ai-keeps-your-postgres-alive-across-host-reboots). The reliability layer the MCP tools sit on top of. - [Deploy a full-stack Python app with Postgres, Redis, and workers in 5 minutes](https://nexusai.run/blog/deploy-full-stack-python-postgres-redis-workers-5-minutes). Hands-on tutorial.