Sunra AI MCP Server: Search, Run, Manage Models

Overview

The Sunra AI MCP (Model Context Protocol) Server provides a simple HTTP API for discovering, running, and managing AI models and the media they produce. It implements the MCP conventions so clients can search model catalogs, submit jobs (inference, render, or media generation), stream or poll job status, and store outputs for downstream consumption. The server is useful for teams that need a central, consistent gateway to different model implementations and media pipelines.

Designed for developer integration, the MCP Server is useful both for rapid experimentation and for production workflows. It exposes model metadata and capabilities, provides job lifecycle management (submit, monitor, cancel), and handles storage and retrieval of generated assets (images, video, 3D). The protocol-focused design simplifies building UI dashboards, automation scripts, or integrating models into larger systems.

Features

• Search and browse available models and capabilities
• Submit model runs (inference, image/video/3D generation)
• Track job lifecycle: queued, running, succeeded, failed, cancelled
• Upload and manage assets produced by runs (download, list, delete)
• Pluggable storage backends (local disk, cloud object stores)
• RESTful API and simple JSON contract for easy integration
• Support for streaming logs and partial results where available
• Lightweight, suitable for local development and cloud deployment

Installation / Configuration

Quick start examples assume the repository contains a server binary or Node service. Adjust to your environment.

Run locally with Node (example):

# clone the repo
git clone https://github.com/sunra-ai/sunra-clients.git
cd sunra-clients/mcp-server

# install and start (Node.js example)
npm install
npm run start

Docker (recommended for isolated runs):

# build and run
docker build -t sunra-mcp-server .
docker run -p 8080:8080 \
  -e PORT=8080 \
  -e STORAGE_PATH=/data/mcp \
  -v /local/path/data:/data/mcp \
  sunra-mcp-server

Example .env configuration:

PORT=8080
STORAGE_BACKEND=local
STORAGE_PATH=/data/mcp
JWT_SECRET=change-me
MAX_CONCURRENT_JOBS=4
LOG_LEVEL=info

Key environment variables:

Available Resources

The server exposes a set of REST endpoints that follow MCP-style conventions. Common endpoints include:

• GET /models — list available models and metadata
• GET /models/{id} — get model details and capabilities
• GET /search?q=… — search models by tag, name, or capability
• POST /runs — submit a new run/job (model id, inputs, params)
• GET /runs/{runId} — get run status and metadata
• GET /runs/{runId}/logs — stream or fetch logs
• POST /runs/{runId}/cancel — cancel a running job
• GET /assets — list generated assets
• GET /assets/{assetId} — download asset
• DELETE /assets/{assetId} — remove asset

Example: submit a run via curl

curl -X POST http://localhost:8080/runs \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-to-image-v1",
    "input": {"prompt":"sunrise over a city skyline"},
    "options": {"width":1024, "height":768}
  }'

Example: poll run status

curl http://localhost:8080/runs/<runId>

Use Cases

• Prototyping a content generation UI: Use /search to populate model picks, submit jobs to /runs, and stream progress to the front end using /runs/{id}/logs and /runs/{id}.
• Automated media pipelines: Kick off long-running generation jobs (video or 3D) from CI or serverless functions, store resulting assets via the server’s storage abstraction, and notify downstream services when jobs complete.
• Model orchestration and comparison: Run the same prompt across multiple models listed under /models and compare outputs, metadata, and performance metrics captured in the run records.
• Asset management: Store generated images, video, or 3D files centrally and use the assets endpoints to manage versions, downloads, and lifecycle (delete old or failed assets).

Integration Tips

• Use the model metadata (capabilities, input schemas) returned by /models to validate inputs before submitting jobs.
• For larger media outputs, prefer streaming or presigned URLs (if supported by your storage backend) to avoid loading files through the server process.
• Respect concurrency limits and use exponential backoff when polling run status in client applications.
• Add authentication (JWT or API keys) in front of the server for production deployments to control who can submit runs or access assets.

The Sunra AI MCP Server provides a protocol-oriented, reusable bridge between AI models and applications. By standardizing job control, search, and asset handling, it reduces integration friction and helps teams build reproducible, automatable model-driven systems.