Skip to main content
Get up and running with NimbleTools Runtime by deploying your first MCP service.

​
Prerequisites

Before starting, make sure you have:
  • ✅ NimbleTools Runtime installed (Installation Guide)
  • ✅ kubectl configured and connected to your cluster
  • ✅ ntcli installed (optional but recommended)

​
Step 1: Verify Runtime Installation

Check that the runtime is running correctly: 
# Check operator status
kubectl get pods -n nimbletools-system

# Verify CRDs are installed
kubectl get crd mcpservices.nimbletools.ai
Expected output: 
NAME                           READY   STATUS    RESTARTS   AGE
nimbletools-operator-xxx       1/1     Running   0          5m
nimbletools-api-xxx            1/1     Running   0          5m

​
Step 2: Create Your First Workspace

Workspaces provide isolation for your MCP services:
  • Using ntcli
  • Using kubectl
# Create workspace
ntcli workspace create my-first-workspace

# Switch to workspace
ntcli workspace select my-first-workspace

# Verify
ntcli workspace list

​
Step 3: Deploy an MCP Service

Let’s deploy the Echo MCP server as an example:
  • Using ntcli
  • Using kubectl
# Deploy from registry
ntcli server deploy echo

# Check status
ntcli server list

# View details
ntcli server info echo
The Echo server is a simple MCP tool that echoes back any message you send it. Perfect for testing!

​
Step 4: Monitor Deployment

Watch your service come online: 
# Watch pods being created
kubectl get pods -n ws-my-first-workspace -w

# Check service status
ntcli server info echo

# View logs
ntcli server logs echo
The first deployment may take 30-60 seconds as the container image is pulled.

​
Step 5: Test Your Service

Once deployed, test the service:
  • Using ntcli
  • Using curl
# List available tools
ntcli mcp tools echo

# Call a tool
ntcli mcp call echo echo_message \
  --input '{"message": "Hello, NimbleTools!"}'
Expected response: 
{
  "content": [
    {
      "type": "text",
      "text": "Echo: Hello, NimbleTools!"
    }
  ]
}

​
Step 6: Connect to Claude Desktop

Generate a configuration to use your service in Claude Desktop: 
# Generate Claude Desktop config
ntcli server claude-config echo
This outputs configuration you can add to your claude_desktop_config.json: 
{
  "mcpServers": {
    "echo": {
      "command": "npx",
      "args": [
        "-y",
        "@nimbletools/mcp-http-bridge",
        "--endpoint",
        "http://localhost:8080/ws/my-first-workspace/echo/mcp",
        "--token",
        "your-workspace-token"
      ]
    }
  }
}
1

Copy the configuration

Copy the generated JSON configuration
2

Open Claude Desktop config

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonOn Windows: %APPDATA%\Claude\claude_desktop_config.json
3

Add to mcpServers section

Paste the configuration into your config file
4

Restart Claude Desktop

Fully quit and restart Claude Desktop
5

Test in Claude

Ask Claude: “Can you echo ‘Hello from NimbleTools’?”

​
Step 7: Scale Your Service

Watch auto-scaling in action: 
# Generate load (in a separate terminal)
for i in {1..100}; do
  ntcli mcp call echo echo_message \
    --input "{\"message\": \"Request $i\"}" &
done

# Watch pods scale up
kubectl get pods -n ws-my-first-workspace -w

# After load stops, watch scale back down to minimum replicas

​
What’s Happening?

When you deploy an MCP service with NimbleTools Runtime:
  1. Custom Resource: A MCPService custom resource is created
  2. Operator Reconciliation: The operator creates a Deployment, Service, and optional HPA
  3. Container Startup: The MCP server starts in a container
  4. Service Registration: The service registers with the runtime’s service registry
  5. Auto-scaling: The service scales based on CPU/memory usage
  6. Load Balancing: Requests are distributed across available replicas

​
Next Steps

Now that you have your first service running, explore more features:

Deploy More Services

Learn about different service types and configurations

Architecture

Understand how the runtime works

CLI Commands

Explore all ntcli commands

GitHub

View source and contribute

​
Troubleshooting

Possible causes:
  • Container image not found
  • Insufficient cluster resources
  • Image pull errors
Solution:
# Check pod events
kubectl describe pod -n ws-my-first-workspace -l app=echo

# View operator logs
kubectl logs -n nimbletools-system -l app=nimbletools-operator
Possible causes:
  • Claude Desktop not restarted
  • Invalid token
  • Port forwarding not active
Solution:
# Verify service is running
ntcli server info echo

# Regenerate token
ntcli token create --name claude-desktop

# Test connection manually
curl http://localhost:8080/ws/my-first-workspace/echo/tools
Possible causes:
  • CPU/memory usage still above target threshold
  • Active connections keeping load high
  • Scale-down cooldown period (default 5 minutes)
Solution:
# Check current scaling config and metrics
kubectl get hpa -n ws-my-first-workspace

# View detailed HPA status
kubectl describe hpa echo -n ws-my-first-workspace

# Check pod metrics
kubectl top pods -n ws-my-first-workspace

​
Learn More

Architecture

Understand how the runtime works

CLI Commands

Explore all ntcli commands

GitHub

View source and contribute

Community

Get help from the community
⌘I