NEXUS AI MCP

By NEXUS AI Team · Contact: nexusai.run/contact

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.

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

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

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

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

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)

Deployments (14 tools)

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)

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)

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

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.

Persistent storage volumes (5 tools)

Org-scoped filesystem mounts. Each volume is single-attach and survives redeploys.

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.

Support (4 tools)

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). 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?. 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. Concrete operations to hand to an agent today.
• 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. Hands-on tutorial.

Start for free · Read the documentation · About NEXUS AI · Contact