Building Smart Agents with MCP and OpenAI gpt-oss

[!NOTE] This post is to be accompanied by it’s GitHub repository here

In this guide, we’ll explore using MCP and demonstrate how to build AI agents using gpt-oss as the LLM backbone. We’ll use Hugging Face’s lightweight MCP clients:

@huggingface/tiny-agents (TypeScript)
huggingface_hub[mcp] (Python)

The key to building effective AI agents lies in their tools. MCP provides a standardized interface for tool interaction, making it simple to create powerful agents.

Let’s dive in by creating a web-savvy agent that can browse and search the internet for you.

Example: Local Browser Agent

Let’s build a browser agent that can browse and search the internet for you. We’ve already implemented this in /browser-agent directory in case you want to skip ahead.

Step 0: Log in to Hugging Face

huggingface-cli login

This will ask you for your HF API token. You can get it from here.

Step 1: Define the Agent

Both the JS and Python Tiny agent clients are meant to be quite easy to play and experiment with. They expect a transparent agent.json which includes the details of which LLM should be used and what tools it should have access to.

Let’s define our agent using OpenAI’s latest gpt-oss 120B as the LLM and connect it to this Playwright MCP server that provides browser automation capabilities to your agent. We’ve added this in /browser-agent/agent.json for you to use.

{
    "model": "openai/gpt-oss-120b",
    "provider": "fireworks-ai",
    "servers": [
        {
            "type": "stdio",
            "command": "npx",
            "args": ["@playwright/mcp@latest"]
        }
    ]
}

Optionally, we can define a System Prompt that helps steer the LLM. This is defined in /browser-agent/PROMPT.md for you to use.

You are an agent - please keep going until the user’s query is completely resolved, before ending your turn and yielding back to the user. Only terminate your turn when you are sure that the problem is solved, or if you need more info from the user to solve the problem.

If you are not sure about anything pertaining to the user’s request, use your tools to read files and gather the relevant information: do NOT guess or make up an answer.

You MUST plan extensively before each function call, and reflect extensively on the outcomes of the previous function calls. DO NOT do this entire process by making function calls only, as this can impair your ability to solve the problem and think insightfully.

Help the User with their task.


That's it, let's take it out for a spin.

### Step 2: Run the agent

To run the agent in Python, we simply install the `tiny-agents` package, which is part of the `huggingface_hub` library.

```bash
pip install -U "huggingface_hub[mcp]>=0.32.0"

Followed by running our agent:

tiny-agents run ./browser-agent

When the agent starts, you can chat with it to ask him to solve tasks. For example, try to ask it to find the top 10 Hugging Face models, and see if it’s able to connect to the website using the Playwright MCP tool we configured!

[!NOTE] You can do exactly the same thing with our JavaScript client as well.
npx @huggingface/tiny-agents run ./browser-agent

Voila, you now have a capable browser agent with you!

Example: Accessing Hugging Face MCP Servers

Let’s take it up a notch and give more creative freedom to our AI Agent, cue, Hugging Face MCP Server. The HF MCP server allows you to not only interact with the HF Hub but also with 1000s of AI spaces on hf.co/spaces.

Let’s get it set up!

Step 1: Find an MCP Server

Head over to hf.co/mcp and add the spaces/ demo that you want to be able to play with

For example, I’ve added the following space

evalstate/FLUX.1-Krea-dev - a popular aesthetic text to image model by Black Forest Labs
evalstate/ltx-video-distilled - a popular image/ text to video by Lightricks

Next, let’s update our agent.json:

{
    "model": "openai/gpt-oss-120b",
    "provider": "fireworks-ai",
    "inputs": [
        {
            "type": "promptString",
            "id": "hf-token",
            "description": "Your Hugging Face Token",
            "password": true
        }
    ],
    "servers": [
        {
            "type": "http",
            "url": "https://huggingface.co/mcp",
            "headers":
            {
                "Authorization": "Bearer ${input:hf-token}"
            }
        }
    ]   
}

Step 2: Run it!

Let’s run it with Tiny agents just like we did with the local browser agent.

tiny-agents run ./hf-mcp-server

[!NOTE] Again, you can do exactly the same thing with our JavaScript client as well.
npx @huggingface/tiny-agents run ./hf-mcp-server

That’s it! What would you build next with it?