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

Besides building a [custom MCP](https://docs.clarifai.com/compute/agents/mcp#build-an-mcp-server) (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`](https://docs.clarifai.com/compute/agents/deploy-mcp/#step-3-prepare-the-configyaml-file) 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](https://mcpservers.org/) or [mcp.so](https://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`](https://github.com/Clarifai/runners-examples/blob/main/llm/agentic-gpt-oss-20b/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)](https://docs.clarifai.com/additional-resources/api-overview/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](https://docs.clarifai.com/compute/inference/#predict-with-openai-compatible-format) 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:

```bash
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](https://docs.clarifai.com/create/applications/create) 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](https://docs.clarifai.com/control/authentication/pat)** (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

```bash
export CLARIFAI_PAT=YOUR_PERSONAL_ACCESS_TOKEN_HERE
```

- Windows

```bash
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:

```text
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`](https://docs.clarifai.com/compute/agents/deploy-mcp/#step-3-prepare-the-configyaml-file) 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:

```python
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:

```yaml
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:

```text
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:

```dockerfile
# 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:

```bash
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:

```python
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:

```python
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.