​
Overview

NimbleTools uses a dual-domain architecture that separates management operations from MCP runtime operations, providing clear separation of concerns and optimized performance for different use cases.

​
Domain Architecture

​
Management API Domain

​
api.nimbletools.dev
string
Handles management operations including workspace administration, token management, server deployment, and configurationPrimary Use: Administrative operations via ntcli
Authentication: Clerk OAuth + Workspace tokens

​
MCP Runtime Domain

​
mcp.nimbletools.dev
string
Handles MCP protocol operations with optimized, simplified URLs for direct server communicationPrimary Use: MCP tool calls and server communication
Authentication: Workspace tokens only

​
URL Structure Comparison

​
Management API Endpoints

Management operations use RESTful URL patterns: 
https://api.nimbletools.dev/v1/workspaces
https://api.nimbletools.dev/v1/workspaces/{uuid}
https://api.nimbletools.dev/v1/workspaces/{uuid}/servers
https://api.nimbletools.dev/v1/workspaces/{uuid}/servers/{server-id}
https://api.nimbletools.dev/v1/workspaces/{uuid}/tokens
https://api.nimbletools.dev/v1/workspaces/{uuid}/secrets

​
MCP Runtime Endpoints

MCP operations use simplified, direct paths for performance: 
https://mcp.nimbletools.dev/{uuid}/{server-id}/mcp
Current Format: 
https://mcp.nimbletools.dev/{uuid}/{server-id}/mcp

​
API Usage by Component

​
ntcli Commands

Command GroupAPI DomainPurpose
authManagementClerk OAuth authentication
workspaceManagementWorkspace CRUD operations
tokenManagementToken lifecycle management
server deploy/list/infoManagementServer deployment and metadata
server logs/scale/removeManagementServer operations
secretsManagementSecret management
mcp connect/tools/callMCP RuntimeDirect MCP protocol operations
server claude-configBothGenerates runtime URLs with management metadata

​
Integration Tools

IntegrationPrimary DomainNotes
Claude DesktopMCP RuntimeUses simplified URLs via HTTP bridge
LangChainMCP RuntimeDirect HTTP calls to MCP endpoints
Custom ScriptsManagementFor deployment, token management
CI/CD PipelinesManagementAutomated deployment workflows

​
Authentication Flow

​
Clerk Authentication (Management)

​
Workspace Token Authentication (Both Domains)

​
Environment Variables

Configure both domains independently: 
# Production (default)
export NTCLI_MANAGEMENT_API_URL=https://api.nimbletools.dev
export NTCLI_MCP_API_URL=https://mcp.nimbletools.dev

# Development
export NTCLI_MANAGEMENT_API_URL=https://dev-api.nimbletools.dev
export NTCLI_MCP_API_URL=https://dev-mcp.nimbletools.dev

# Enterprise
export NTCLI_MANAGEMENT_API_URL=https://management.company.com
export NTCLI_MCP_API_URL=https://mcp.company.com

​
Benefits of Dual-Domain Architecture

​
Performance Optimization

  • MCP Runtime: Simplified URLs reduce parsing overhead
  • Management API: RESTful structure for complex operations
  • Caching: Domain-specific caching strategies
  • Load Balancing: Independent scaling per domain

​
Security Separation

  • Management API: Full authentication and authorization
  • MCP Runtime: Streamlined token-only authentication
  • Rate Limiting: Different limits per domain and use case
  • Monitoring: Separate metrics and logging

​
Development Experience

  • Clear Separation: Management vs. runtime operations
  • Simpler Integration: Direct MCP URLs for external tools
  • Better Debugging: Domain-specific error handling
  • Future Extensibility: Independent domain evolution

​
Error Handling

​
Management API Errors

{
  "error": {
    "code": "WORKSPACE_NOT_FOUND",
    "message": "Workspace not found",
    "details": {"workspace_id": "uuid"}
  }
}

​
MCP Runtime Errors

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": {"details": "Server not found"}
  }
}

​
Common Error Resolution

ErrorDomainSolution
401 UnauthorizedManagementRun ntcli auth login
401 UnauthorizedMCP RuntimeRun ntcli token refresh
404 Not FoundManagementCheck workspace/server exists
404 Not FoundMCP RuntimeVerify server deployment status

Environment Variables

Configure API endpoints

Token Management

Workspace token operations

Claude Integration

MCP runtime usage examples

LangChain Integration

Custom MCP runtime integration