Model Download MCP Server#

Every Model Download deployment exposes an MCP (Model Context Protocol) server at /mcp alongside the REST API. LLM agents (Claude Desktop, GitHub Copilot, and custom AI agents) can therefore download, convert, and manage AI models through MCP without deploying a second service.

Quick Start#

Recommended: Container MCP Endpoint#

Deploy the Model Download service first, then configure MCP clients to connect to the HTTP MCP endpoint exposed by that deployment. This is required for OpenVINO/OVMS conversions because the container entrypoint:

downloads the OVMS export_model.py script;
creates the dedicated OpenVINO plugin virtual environment;
installs the matching conversion dependencies; and
records the plugin environment in /opt/plugin_venvs.env.

Start the service with the plugins required for Hugging Face downloads and OpenVINO conversion:

cd edge-ai-libraries/microservices/model-download

# Required only for gated/private Hugging Face models. The environment-variable
# path expects the plain-text token, not a base64-encoded value.
export HUGGINGFACEHUB_API_TOKEN='hf_xxx'

source scripts/run_service.sh up \
  --plugins huggingface,openvino \
  --model-path "$PWD/models"

Verify the service before configuring the MCP client:

curl http://localhost:8200/api/v1/health
# Expected: {"status":"ok"}

Connect MCP clients to:

http://localhost:8200/mcp

The deployment serves both interfaces on port 8200:

Interface	Default URL
REST API	Existing REST endpoints on `http://localhost:8200`
MCP server	`http://localhost:8200/mcp`

Available MCP Tools#

Tool	Description
`health_check`	Check service health
`download_model`	Submit a model download/conversion job
`get_job_status`	Get status of a specific job by ID
`list_jobs`	List all jobs
`cancel_job`	Cancel a running or queued job
`get_model_jobs`	Get all jobs for a specific model name
`get_model_results`	Get completed downloads/conversions
`list_plugins`	List available plugins and capabilities
`list_hub_models`	Browse/search models on a hub

Available MCP Resources#

URI	Description
`models://jobs`	All job records
`models://jobs/{job_id}`	A specific job by ID
`models://results`	Completed download/conversion results
`models://plugins`	Available plugins and capabilities

Client Configuration Examples#

GitHub Copilot#

First deploy the service as described in Recommended: Container MCP Endpoint. Then remove any existing local/stdio configuration and connect Copilot directly to the same HTTP MCP endpoint used by the REST service and MCP Inspector:

copilot mcp add \
  --transport http \
  --tools '*' \
  oep-model-download \
  http://localhost:8200/mcp

If the MCP endpoint is on another host, replace localhost with the hostname used by MCP Inspector. After adding or changing the server, restart Copilot CLI or reload the server through /mcp.

This configuration ensures REST, MCP Inspector, and Copilot share the same container-initialized plugin environment, model store, and job manager.

Verify the MCP Connection#

After adding or changing the configuration, restart the MCP client or reload its MCP servers. Then use the client’s tool view or chat interface to perform these checks:

Confirm that the model-download server is connected and exposes the nine tools listed in Available MCP Tools.
Ask the client to call health_check from the model-download server. A working server returns:

{"status": "ok"}

Ask the client to call list_plugins. Check that available_count is greater than zero and that the required hub has "available": true.
Optionally call list_jobs. A new installation normally returns an empty list:

{"jobs": []}

For example, in GitHub Copilot chat, ask:

Use the model-download MCP server to run health_check, then list the available plugins.

End-to-End Download Check#

This check requires network access and an available huggingface plugin. It downloads a small test model into MODELS_DIR:

Call download_model with:

{
  "name": "hf-internal-testing/tiny-random-bert",
  "hub": "huggingface",
  "download_path": "mcp-smoke-test"
}

Copy a returned ID from job_ids and call get_job_status with:

{"job_id": "<returned-job-id>"}

Poll get_job_status until the status is completed or failed. On success, call get_model_results and verify that the model path exists under MODELS_DIR/mcp-smoke-test.

For an HTTP configuration, verify the container endpoint and the Copilot configuration:

curl http://localhost:8200/api/v1/health
copilot mcp get oep-model-download

For OpenVINO conversion failures that occur only in Copilot CLI:

Check whether copilot mcp get oep-model-download reports Type: local.
If it does, the CLI is launching a separate standalone stdio server rather than using the container runtime.
Replace that configuration with the HTTP configuration shown in GitHub Copilot.

Remote HTTP Client (Python)#

import asyncio
from fastmcp import Client

client = Client("http://localhost:8200/mcp")

async def main():
    async with client:
        # Download a model
        result = await client.call_tool("download_model", {
            "name": "meta-llama/Llama-3.2-1B",
            "hub": "huggingface",
        })
        print(result)

        # Check job status
        status = await client.call_tool("get_job_status", {
            "job_id": "<job-id-from-above>"
        })
        print(status)

asyncio.run(main())

Environment Variables#

The MCP server uses the same environment variables as the REST API:

Variable	Description	Default
`MODELS_DIR`	Base directory for downloaded models	`./models` locally; `/opt/models` in the container
`HUGGINGFACEHUB_API_TOKEN` / `HF_TOKEN`	Plain-text Hugging Face API token for gated/private models	—
`ENABLED_PLUGINS`	Comma-separated list of plugins to activate	`all`

REST API vs MCP Server#

Both modes share the same core logic (ModelManager, PluginRegistry). Choose based on your use case:

	Default deployment	Standalone MCP
Use when	Applications need REST/MCP, or any OpenVINO/OVMS conversion	Download-only local development
Transport	REST and Streamable HTTP	stdio or Streamable HTTP
Client	HTTP and MCP clients	MCP-compatible clients
OpenVINO bootstrap	Performed by the container entrypoint	Not performed automatically