Hugging Face Tiny Agents: Building MCP-Powered Agents in 50 Lines of Code

Hugging Face has demonstrated that with the Model Context Protocol (MCP) and native tool-calling support in modern LLMs, a functional AI agent can be implemented in approximately 50 lines of code. The core realization is that once an MCP client is established to handle tool discovery and execution, an agent is essentially just a while loop that alternates between LLM inference and tool execution.

The Model Context Protocol (MCP) as a Tooling Standard

MCP serves as a standard API to expose sets of tools that can be integrated with LLMs. By using MCP, developers can decouple the tools from the LLM implementation, allowing an inference client to hook available tools from various MCP servers into the model's inference process.

Currently, MCP servers operate as local processes. Hugging Face's implementation utilizes the @modelcontextprotocol/sdk/client TypeScript SDK to connect to these servers and retrieve available tools via the listTools() method. These tools are then reformatted into a JSONSchema representation (name, description, and parameters) that is compatible with native LLM tool-calling interfaces.

Implementing an MCP Client with InferenceClient

To build an MCP-powered agent, Hugging Face utilizes the InferenceClient from the @huggingface/inference JS library. The architecture consists of three primary components:

  1. Inference Client: Manages the connection to the LLM provider (e.g., Nebius) and the model (e.g., Qwen2.5-72B-Instruct).
  2. MCP Client Sessions: Maintains a map of sessions for each connected MCP server to handle tool execution.
  3. Tool Registry: A list of available tools aggregated from all connected MCP servers.

When the LLM generates a tool call, the client identifies the correct MCP session and uses the client.callTool() method to execute the function and retrieve the result, which is then fed back into the LLM as a tool message.

Agent Architecture: The "While Loop" Logic

An agent is defined as the combination of a system prompt, an LLM inference client, an MCP client, and basic control flow. Hugging Face avoids manually injecting tool descriptions into the prompt, instead relying on the native tools parameter of the inference engine.

Control Flow and Loop Termination

The agent's main loop iterates between tool calling and feeding results back to the LLM. The loop terminates under the following conditions:

  • Explicit Task Completion: The LLM calls a specific task_complete tool.
  • User Interaction: The LLM calls an ask_question tool to request more information from the user.
  • Turn Limit: The number of turns exceeds a predefined MAX_NUM_TURNS.
  • Response Pattern: The loop breaks when the LLM responds with two non-tool messages in a row.

Practical Application and Demo

Users can run the complete demo via npx @huggingface/mcp-client. The default configuration connects to two local MCP servers:

  • File System Server: Grants the agent access to the local desktop for reading and writing files.
  • Playwright MCP Server: Provides a sandboxed Chromium browser for web navigation and searching.

For example, the agent can handle complex multi-step prompts such as writing a haiku to a file on the desktop or performing a Brave Search for inference providers and opening the top three results.

Technical Specifications and Extensibility

  • Default Model: Qwen/Qwen2.5-72B-Instruct
  • Default Provider: Nebius
  • Language: TypeScript/JavaScript (utilizing async generators for LLM responses).
  • Extensibility: The system is designed to work with any OpenAI-compatible client SDK and various inference providers including Cerebras, Cohere, Fireworks, and others. It also supports local LLMs via llama.cpp or LM Studio.

Sources