MCP Hosting API

Endpoints for provisioning and managing private MCP servers. Available to Studio tier organizations only.

Overview

Studio tier organizations can host private MCP (Model Context Protocol) servers managed by Nexus Suite. Each server runs in an isolated container with network access restricted to authenticated organization members.

Limits

• Maximum 5 private MCP server instances per Studio organization
• Servers can be deployed from a Git repository URL or a pre-built container image

Provision a Server

Create a new private MCP server instance.

POST /v1/mcp/servers
Authorization: Bearer <jwt>

Requires Studio tier admin role.

Body:

{
  "name": "my-database-tools",
  "source_type": "git",
  "source_url": "https://github.com/org/mcp-server.git"
}

Field	Required	Description
name	Yes	Display name for the server
source_type	Yes	git (build from repo) or image (pre-built container)
source_url	Yes	Git repository URL or container image reference

Response: 201 Created

{
  "data": {
    "id": "mcp_abc123",
    "name": "my-database-tools",
    "status": "provisioning",
    "source_type": "git",
    "source_url": "https://github.com/org/mcp-server.git",
    "endpoint_url": null,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

The server starts in provisioning status. Once the container is built and running, the status changes to running and endpoint_url is populated.

Errors:

Code	Condition
TIER_REQUIRED	User is not on Studio tier
FORBIDDEN	User does not have admin role in the organization
QUOTA_EXCEEDED	Organization has reached the 5-server limit

List Servers

List all MCP servers for the organization.

GET /v1/mcp/servers
Authorization: Bearer <jwt>

Response: 200 OK

{
  "data": {
    "servers": [
      {
        "id": "mcp_abc123",
        "name": "my-database-tools",
        "status": "running",
        "endpoint_url": "wss://mcp.nexus-suite.dev/mcp_abc123",
        "source_type": "git",
        "source_url": "https://github.com/org/mcp-server.git",
        "created_by": "usr_xyz789",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "limit": 5,
    "used": 1
  }
}

Server Statuses

Status	Description
provisioning	Container is being built and deployed
running	Server is active and accepting connections
stopped	Server has been stopped
error	Deployment or runtime error occurred

Get Server Details

Get detailed information about a specific MCP server, including recent logs.

GET /v1/mcp/servers/:id
Authorization: Bearer <jwt>

Response: 200 OK

{
  "data": {
    "id": "mcp_abc123",
    "name": "my-database-tools",
    "status": "running",
    "endpoint_url": "wss://mcp.nexus-suite.dev/mcp_abc123",
    "source_type": "git",
    "source_url": "https://github.com/org/mcp-server.git",
    "container_id": "ctr_def456",
    "created_by": "usr_xyz789",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:35:00Z",
    "logs": [
      {
        "timestamp": "2024-01-15T10:35:00Z",
        "level": "info",
        "message": "MCP server started on port 3000"
      }
    ]
  }
}

Connect to Server

Get connection credentials for an MCP server. The returned credentials are used by NexusIDE and NexusCore CLI to establish a connection.

POST /v1/mcp/servers/:id/connect
Authorization: Bearer <jwt>

Response: 200 OK

{
  "data": {
    "endpoint_url": "wss://mcp.nexus-suite.dev/mcp_abc123",
    "token": "mcp_conn_token_...",
    "expires_in": 3600
  }
}

The connection token is scoped to the requesting user and expires after 1 hour. RBAC permissions are verified — the user must have access to the server.

Deprovision a Server

Remove a private MCP server instance.

DELETE /v1/mcp/servers/:id
Authorization: Bearer <jwt>

Requires Studio tier admin role.

Response: 204 No Content

WARNING

This permanently stops and removes the server container. All server data is deleted. This action cannot be undone.