Nexlayer MCP — Better Docs

Nexlayer is an AI-native deployment platform. It exposes a Model Context Protocol (MCP) server so your AI coding assistant (Claude Code, Cursor, etc.) can deploy and manage containerized applications directly from conversation.

The official docs describe what tools exist. This reference tells you exactly how to call them — parameters, types, responses, and copy-paste examples.

Quick Install

Auto-detects all installed AI coding tools and configures them simultaneously.

Claude Code — Manual Setup

Add the Nexlayer MCP server to your Claude Code settings:

{
  "mcpServers": {
    "nexlayer": {
      "type": "http",
      "url": "https://mcp.nexlayer.ai/api/mcp"
    }
  }
}

WebSocket Bridge (for Claude Code ≤ native ws)

Claude Code supports stdio, sse, and http transports. If you need WebSocket:

Or manually:

# Install bridge globally
npm install -g nexlayer-mcp-ws

# Register with Claude Code
claude mcp add nexlayer-mcp -- nexlayer-mcp-ws

# With auth token
claude mcp add -e NEXLAYER_MCP_TOKEN=your-token nexlayer-mcp -- nexlayer-mcp-ws

Verify Installation

After setup, ask your AI assistant: "List my Nexlayer deployments". If the MCP is connected, it will call the tools and respond with your deployment list.

Quickstart

Deploy a containerized app to a live URL in under 60 seconds.

1. Write nexlayer.yaml

application:
  name: my-app

pods:
  - name: web
    image: nginx:alpine
    path: /
    servicePorts: [80]

2. Ask Claude to deploy

# In your Claude Code session:
Deploy my-app using this nexlayer.yaml

Claude calls deploy_application and returns a live URL like jolly-tapir-my-app.cloud.nexlayer.ai.

3. Check status & logs

# Ask Claude:
What's the status of my-app?
Show me logs for my-app

MCP Tools Reference

The Nexlayer MCP server exposes these tools to AI assistants. Each tool maps to an action on your deployments.

{
  "message":         "Deployment started successfully",
  "url":             "https://jolly-tapir-my-app.cloud.nexlayer.ai",
  "sessionToken":    "dCf0NdAQ64j6",
  "applicationName": "my-app",
  "environment":     "jolly-tapir",
  "status":         "starting"
}

# Claude will read your nexlayer.yaml and call deploy_application automatically
Deploy the application defined in my nexlayer.yaml

curl -X POST https://app.nexlayer.com/startUserDeployment \
  -H "Content-Type: text/x-yaml" \
  --data-binary @nexlayer.yaml

{
  "applicationName": "my-app",
  "status":          "running",  // starting | running | error | stopped
  "url":            "https://jolly-tapir-my-app.cloud.nexlayer.ai",
  "pods": [
    {
      "name":    "web",
      "status": "running",
      "image":  "nginx:alpine"
    }
  ]
}

What's the deployment status of my-app?

# All pods
Show me logs for my-app

# Specific pod
Show logs for the api pod in my-app

# Debug: look for errors
Get the last 200 log lines from my-app and look for errors

Type: CNAME
Name: www
Value: cname.nexlayer.dev

Type: A     | Name: @   | Value: 76.76.21.21
Type: CNAME | Name: www | Value: cname.nexlayer.dev

application:
  name: my-app
  url: www.mysite.com  # custom domain goes here

# Set a secret
Set DATABASE_URL to postgres://user:[email protected]:5432/mydb for my-app

# Update API key
Update the OPENAI_API_KEY env var for the api pod in my-app

pods:
  - name: api
    vars:
      DATABASE_URL: "postgres://user:[email protected]:5432/mydb"
      REDIS_URL:    "redis://redis.pod:6379"
      NODE_ENV:     production

# Scale up API tier
Scale the api pod in my-app to 3 replicas

# Scale back down
Set my-app api pod to 1 replica

pods:
  - name: api
    replicas: 3       # fixed — disables auto-scale
    resources:
      cpu: "2"        # 2 CPU cores
      memory: "4Gi"   # 4 GB RAM

[
  {
    "applicationName": "my-app",
    "status":          "running",
    "url":            "https://jolly-tapir-my-app.cloud.nexlayer.ai",
    "createdAt":      "2026-04-25T10:00:00Z",
    "expiresAt":      "2026-04-27T10:00:00Z"
  }
]

List all my Nexlayer deployments

nexlayer.yaml Schema

The single config file that defines your entire deployment. Nexlayer keeps it intentionally minimal.

Top-level fields

Pod fields

YAML Examples

Minimal — static site

application:
  name: my-site

pods:
  - name: web
    image: nginx:alpine
    path: /
    servicePorts: [80]

Full-stack app (Next.js + PostgreSQL + Redis)

application:
  name: myapp
  url: www.myapp.com

pods:
  - name: web
    image: ghcr.io/myorg/myapp:latest
    path: /
    servicePorts: [3000]
    vars:
      DATABASE_URL: "postgres://app:[email protected]:5432/myapp"
      REDIS_URL:    "redis://redis.pod:6379"
      NODE_ENV:     production

  - name: postgres
    image: postgres:16-alpine
    path: /db
    servicePorts: [5432]
    vars:
      POSTGRES_USER:     app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB:       myapp
    volumes:
      - name: pg-data
        size: "10Gi"
        mountPath: "/var/lib/postgresql/data"

  - name: redis
    image: redis:7-alpine
    path: /cache
    servicePorts: [6379]

AI inference (LLM serving)

application:
  name: llm-server

pods:
  - name: ollama
    image: ollama/ollama:latest
    path: /
    servicePorts: [11434]
    resources:
      cpu: "4"
      memory: "16Gi"
    volumes:
      - name: models
        size: "50Gi"
        mountPath: "/root/.ollama"

Multi-path API gateway

application:
  name: gateway

pods:
  - name: web
    image: myorg/frontend:latest
    path: /
    servicePorts: [3000]

  - name: api
    image: myorg/api:latest
    path: /api
    servicePorts: [8080]
    replicas: 3
    vars:
      BACKEND_URL: "http://web.pod:3000"

Environment Variables

Set in the vars block per pod, or via the set_environment_variable MCP tool at runtime.

Inter-pod references

Pods communicate internally using the <pod-name>.pod:<port> format:

vars:
  DATABASE_URL: "postgres://user:[email protected]:5432/mydb"
  REDIS_URL:    "redis://redis.pod:6379"
  API_URL:      "http://api.pod:8080"

Volumes (Persistent Storage)

volumes:
  - name: my-data       # identifier
    size: "2Gi"          # storage capacity
    mountPath: "/data"  # where it mounts inside the container

API — Authentication

Base URL: https://app.nexlayer.com

Nexlayer uses session tokens generated when you first deploy. Provide the token as a query parameter or in the request body.

# Query parameter
GET /getReservations?sessionToken=dCf0NdAQ64j6

# Request body
POST /extendDeployment
{ "sessionToken": "dCf0NdAQ64j6", "applicationName": "my-app" }

API — Deploy Endpoints

curl -X POST https://app.nexlayer.com/startUserDeployment \
  -H "Content-Type: text/x-yaml" \
  --data-binary @nexlayer.yaml

curl -X POST \
  "https://app.nexlayer.com/updateUserDeployment?sessionToken=TOKEN" \
  -H "Content-Type: text/x-yaml" \
  --data-binary @nexlayer.yaml

curl -X POST https://app.nexlayer.com/extendDeployment \
  -H "Content-Type: application/json" \
  -d '{ "sessionToken": "TOKEN", "applicationName": "my-app" }'

curl -X POST https://app.nexlayer.com/claimDeployment \
  -H "Content-Type: application/json" \
  -d '{ "sessionToken": "TOKEN", "applicationName": "my-app" }'

API — Manage Endpoints

curl "https://app.nexlayer.com/getReservations?sessionToken=TOKEN"

curl -X POST https://app.nexlayer.com/addDeploymentReservation \
  -d '{ "sessionToken": "TOKEN", "applicationName": "my-app" }'

curl -X POST https://app.nexlayer.com/removeDeploymentReservation \
  -d '{ "sessionToken": "TOKEN", "applicationName": "my-app" }'

curl -X POST https://app.nexlayer.com/removeReservations \
  -d '{ "sessionToken": "TOKEN" }'

Guide — Custom Domains

Step 1: Add domain to nexlayer.yaml

application:
  name: my-app
  url: www.mysite.com

Step 2: Configure DNS

At your DNS provider (Cloudflare, Route 53, etc.):

For www subdomain:

CNAME  www  cname.nexlayer.dev

For root apex domain:

A      @    76.76.21.21
CNAME  www  cname.nexlayer.dev

Step 3: Deploy

SSL is automatically provisioned on first request to the domain. No further action needed.

Guide — Scaling & Resources

Nexlayer auto-scales by default based on CPU/memory. Set replicas to fix the count (disables auto-scale).

Auto-scaling (default)

pods:
  - name: api
    # no replicas field → Nexlayer auto-scales

Fixed replicas

pods:
  - name: api
    replicas: 3

Custom resources

pods:
  - name: heavy-worker
    resources:
      cpu: "2"
      memory: "8Gi"

Best practices for scale

• Stateless design — store sessions in Redis, files in object storage
• Health endpoint — expose /health returning HTTP 200 when ready
• Graceful shutdown — handle SIGTERM to drain in-flight requests
• Databases — use a managed service for stateful, high-availability data

Guide — Service Discovery

Pods within the same deployment communicate via internal DNS: <pod-name>.pod:<port>.

# From any pod in the deployment:
postgres.pod:5432    # PostgreSQL
redis.pod:6379       # Redis
api.pod:8080         # Internal API
worker.pod:9000      # Background worker

Guide — Health Checks

Expose a /health endpoint from your app. Nexlayer uses it to determine if a pod should receive traffic.

Node.js / Express

app.get('/health', (req, res) => res.json({ status: 'ok' }));

Python / FastAPI

@app.get("/health")
def health(): return {"status": "ok"}

Go

http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
  w.WriteHeader(http.StatusOK)
  w.Write([]byte(`{"status":"ok"}`))
})

Unhealthy instances are automatically removed from the load balancer and replaced.