Deploy Open-Source MCP Servers | Clarifai Docs

Upload, deploy, and interact with open-source MCP servers on Clarifai

Besides building a custom MCP (Model Context Protocol) server for the Clarifai platform, you can also upload any open-source MCP server and expose it as a managed API endpoint — just like any model in the platform.

You can easily integrate third-party MCP servers with Clarifai by simply adding the mcp_server configuration to your config.yaml file.

This allows you to:

Expose MCP servers as HTTP APIs accessible through Clarifai
Use the FastMCP client to interact with deployed MCP servers
Seamlessly integrate MCP tools with LLMs to extend model capabilities

Step 1: Perform Prerequisites

Get an MCP Server

You can get open-source MCP servers from third-party repositories, such as mcpservers.org or mcp.so.

Get an Agentic Model

Integrating large language models (LLMs) with MCP servers enables agentic capabilities, allowing models to discover and use external tools autonomously to complete tasks. MCP servers expose functionalities that models can invoke as function-calling tools during conversations.

With MCP server integration, an agentic model can iteratively discover tools, execute them, and reason over the results to produce more capable and context-aware responses.

Note: For a model to support agentic behavior through MCP servers on the Clarifai platform, it must extend the standard OpenAIModelClass with the AgenticModelClass. This enables:

Tool discovery and execution handled by the agentic model class

Iterative tool calling within a single predict or generate request

Compatibility with the OpenAI-compatible API and Clarifai SDKs

Support for both streaming and non-streaming modes

The AgenticModelClass manages the full agentic loop: it discovers available MCP tools at model load time, injects them into the LLM context, and iteratively calls tools and feeds results back to the model until a final response is produced.

You can see an example implementation of AgenticModelClass in this 1/model.py file.

Install Packages

Install the following Python packages to work with the DuckDuckGo Browser MCP server:

clarifai — The latest version of the Clarifai Python SDK, required to integrate your MCP server with the Clarifai platform. This package also comes with the Clarifai Command Line Interface (CLI), which you’ll use to upload the server.
fastmcp — The core framework for interacting with MCP servers.
openai — This leverages Clarifai’s OpenAI-compatible endpoint endpoint to run inferences using the OpenAI client library.
anyio — An asynchronous I/O library used by FastMCP.
requests — A lightweight HTTP client for making HTTP requests.
mcp — The Model Context Protocol library.

You can run the following command to install them:

pip install --upgrade clarifai fastmcp openai anyio requests mcp

Get Credentials

You need to have the following Clarifai credentials:

App ID — Create a Clarifai application and get its ID. This is where your MCP server will reside on the Clarifai platform.
User ID — In the collapsible left sidebar, select Settings and choose Account from the dropdown list. Then, locate your user ID.
Personal Access Token (PAT) — From the same Settings option, choose Secrets to generate or copy your PAT. This token is used to authenticate your connection with the Clarifai platform.

Then, set the CLARIFAI_PAT as an environment variable.

Unix-Like Systems

export CLARIFAI_PAT=YOUR_PERSONAL_ACCESS_TOKEN_HERE

Windows

set CLARIFAI_PAT=YOUR_PERSONAL_ACCESS_TOKEN_HERE

Create Files

On the Clarifai platform, MCP servers are treated just like models and follow the same underlying architecture.

To upload an MCP server, you need to create a project directory and organize your files according to Clarifai’s custom model requirements, as shown below:

your_model_directory/
├── 1/
│   └── model.py
├── requirements.txt
├── config.yaml
├── Dockerfile
└── client.py

Create a Cluster and Nodepool

You'll need to deploy your MCP server to a dedicated compute cluster and nodepool. This action provisions the necessary resources to run your server and handle requests efficiently.

Note: Ensure that your cluster and nodepool meet the compute resource requirements specified in your config.yaml file.

Step 2: Prepare `model.py` File

When building a custom MCP server from scratch, model.py is where you implement the server’s core logic, including defining and exposing tools.

However, when uploading an open-source MCP server, you do not need to reimplement this logic. Instead, you only need to define a class that inherits from StdioMCPModelClass, which is designed to run and manage stdio-based MCP servers, such as the Browser MCP server.

Here is the model.py file that defines a StdioMCPModelClass for the Browser MCP server:

from clarifai.runners.models.stdio_mcp_class import StdioMCPModelClass

class BrowserMCPServerClass(StdioMCPModelClass):
    pass

Step 3: Prepare the `config.yaml` File

The config.yaml file defines the build, deployment, and runtime configuration for a custom model — or, in this case, an MCP server — on the Clarifai platform. It tells Clarifai how to build the execution environment and where the server should live within your account.

Here is the config.yaml file for the Browser MCP server:

model:
  id: browser-mcp-server
  app_id: app_id
  user_id: user_id
  model_type_id: mcp

build_info:
  python_version: "3.11"

inference_compute_info:
  cpu_limit: 1000m
  cpu_memory: 1Gi
  num_accelerators: 0

mcp_server:
  command: "uvx"
  args: ["duckduckgo-mcp-server"]

Step 4: Define Dependencies in `requirements.txt`

The requirements.txt file specifies all Python packages required by your MCP server. During deployment, Clarifai uses this file to automatically install the necessary dependencies, ensuring the server runs correctly in its runtime environment.

Here is the requirements.txt file for the custom model — or, in this case, the MCP server — we want to upload:

clarifai==12.1.7
anyio
mcp==1.26.0
fastmcp==2.14.5
requests>=2.31.0

Step 5: Define Dockerfile

The Dockerfile defines the container environment used to build and run the MCP server on the Clarifai platform.

Here is the Dockerfile file for the Browser MCP server:

# syntax=docker/dockerfile:1.13-labs

FROM --platform=$TARGETPLATFORM python:3.12-slim

COPY --link requirements.txt /home/nonroot/requirements.txt

# Update clarifai package so we always have latest protocol to the API. Everything should land in /venv
RUN ["pip", "install", "--no-cache-dir", "-r", "/home/nonroot/requirements.txt"]
RUN ["pip", "show", "--no-cache-dir", "clarifai"]

# Set the NUMBA cache dir to /tmp
# Set the TORCHINDUCTOR cache dir to /tmp
# The CLARIFAI* will be set by the templating system.
ENV NUMBA_CACHE_DIR=/tmp/numba_cache \
    TORCHINDUCTOR_CACHE_DIR=/tmp/torchinductor_cache \
    HOME=/tmp \
    DEBIAN_FRONTEND=noninteractive

COPY --link=true config.yaml /home/nonroot/main/

COPY --link=true 1 /home/nonroot/main/1

# At this point we only need these for validation in the SDK.
COPY --link=true requirements.txt config.yaml /home/nonroot/main/

# Add the model directory to the python path.
ENV PYTHONPATH=${PYTHONPATH}:/home/nonroot/main \
    CLARIFAI_PAT=${CLARIFAI_PAT} \
    CLARIFAI_USER_ID=${CLARIFAI_USER_ID} \
    CLARIFAI_RUNNER_ID=${CLARIFAI_RUNNER_ID} \
    CLARIFAI_NODEPOOL_ID=${CLARIFAI_NODEPOOL_ID} \
    CLARIFAI_COMPUTE_CLUSTER_ID=${CLARIFAI_COMPUTE_CLUSTER_ID} \
    CLARIFAI_API_BASE=${CLARIFAI_API_BASE:-https://api.clarifai.com}

WORKDIR /home/nonroot/main

ENTRYPOINT ["python", "-m", "clarifai.runners.server"]
CMD ["--model_path", "/home/nonroot/main"]

Step 6: Upload to Clarifai

To upload your open-source MCP server to the Clarifai platform, navigate to the server’s root directory and run:

clarifai model upload . --skip_dockerfile

This command will upload the MCP server to your Clarifai account.

Step 7: Deploy the Model

After uploading the MCP server, you must deploy it to a dedicated compute cluster and nodepool. Deployment provisions the compute resources required to run the server and handle incoming requests.

Step 8: Interact with the Server

Once the open-source MCP server is deployed, you can create a client script to communicate with it and invoke the exposed MCP tools. This allows agentic models to discover and use the server’s capabilities programmatically.

Use with FastMCP Client

Here is an example of interacting with the MCP server directly using the FastMCP client without going through an LLM:

import asyncio
import os
from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

transport = StreamableHttpTransport(
    url="https://api.clarifai.com/v2/ext/mcp/v1/users/{user_id}/apps/{app_id}/models/{model_id}",
    headers={
        "Authorization": f"Bearer {os.environ['CLARIFAI_PAT']}",
    },
)

async def main():
    async with Client(transport) as client:
        tools = await client.list_tools()
        print("Available tools:")
        for tool in tools:
            print(f"- {tool.name}")

if __name__ == "__main__":
    asyncio.run(main())

Integrate with LLMs

Here is an example of how to bridge an MCP server with an agentic LLM on Clarifai:

import asyncio
import os
import json
from openai import AsyncOpenAI
from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

# MCP client setup
transport = StreamableHttpTransport(
    url="https://api.clarifai.com/v2/ext/mcp/v1/users/{user_id}/apps/{app_id}/models/{model_id}",
    headers={
        "Authorization": f"Bearer {os.environ['CLARIFAI_PAT']}",
    },
)

# OpenAI-compatible client (Clarifai)
openai_client = AsyncOpenAI(
    api_key=os.environ["CLARIFAI_PAT"],
    base_url="https://api.clarifai.com/v2/ext/openai/v1",
)

async def main():
    async with Client(transport) as mcp_client:
        tools_raw = await mcp_client.list_tools()

if __name__ == "__main__":
    asyncio.run(main())

Note: The DuckDuckGo MCP server provides various tools for web search and information retrieval.