Local Hugging Face MCP Server

A production-ready local MCP (Model Context Protocol) server built with Node.js (ES Modules) that can be connected to Agent Studio via its MCP Servers feature.

Features

• Exposes multiple tools to Agent Studio:

  • Calculator: Performs basic arithmetic operations

  • Search: Returns mocked search results (easy to replace with real search)

  • Chat: Simple greeting response

  • Hugging Face: Interfaces with Hugging Face Inference API for text generation

• Secure: Optional API token authentication

• Environment configurable

• Health check endpoint

• Comprehensive error handling

• Logging of requests and tool invocations

• Built with the latest official @modelcontextprotocol/sdk

Related MCP server: production-grade-mcp-agentic-system

Installation

1. Clone or download this repository

2. Install dependencies:

npm install

Environment Variables

Create a .env file in the root directory with the following variables:

PORT=8000
ACCESS_TOKEN=my-secret-token
HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• PORT: The port the server will listen on (default: 8000)

• ACCESS_TOKEN: Optional. If set, requires Authorization: Bearer <token> header for MCP endpoint. If empty or not set, allows anonymous access.

• HF_TOKEN: Your Hugging Face Inference API token (required for the Hugging Face tool)

Getting a Hugging Face Token

1. Go to Hugging Face Settings

2. Create a new token with "Read" access (for inference API)

3. Copy the token and set it as HF_TOKEN in your .env file

Usage

Starting the Server

Production

npm start

Development (with auto-restart)

npm run dev

The server will start at http://localhost:8000.

Endpoints

• GET / - Returns "MCP Server Running"

• GET /health - Returns { "status": "ok" }

• POST /mcp - MCP endpoint for Agent Studio (requires authentication if ACCESS_TOKEN is set)

Connecting to Agent Studio

1. Open Agent Studio

2. Navigate to Settings → MCP Servers

3. Click "Add New Server"

4. Fill in the form:

   • Name: Local MCP

   • Server URL: http://localhost:8000/mcp

   • Access Token: my-secret-token (if you set ACCESS_TOKEN in .env; leave blank if not set)

5. Save the connection

Agent Studio will now be able to discover and use the tools exposed by this MCP server.

Available Tools

Calculator

Performs basic arithmetic operations.

Input:

{
  "a": number,
  "b": number,
  "operation": "add" | "subtract" | "multiply" | "divide"
}

Output: Result = <result>

Errors: Throws an error for division by zero.

Search

Returns mocked search results (replace with real search implementation).

Input:

{
  "query": string
}

Output:

{
  "results": [
    {
      "title": string,
      "url": string,
      "snippet": string
    }
  ]
}

Chat

Simple greeting tool.

Input:

{
  "message": string
}

Output: Hello from MCP

Hugging Face

Interfaces with Hugging Face Inference API for text generation.

Input:

{
  "model": string,  // e.g., "gpt2"
  "prompt": string
}

Output: Generated text string from the model.

Errors:

• HF_TOKEN is not set in environment variables - Missing Hugging Face token

• Invalid Hugging Face token - 401 from HF API

• Model not found: <model> - 404 from HF API

• Rate limit exceeded - 429 from HF API

• Request to Hugging Face API timed out - Timeout after 10 seconds

• Hugging Face API error: <status> <message> - Other HTTP errors

• Unexpected error: <message> - Other unexpected errors

Extending with Additional Tools

To add a new tool:

1. Create a new file in the tools/ directory (e.g., mytool.js)

2. Export a handler function and a Zod schema:

   import { z } from 'zod';
   
   export const mytoolTool = async (input) => {
     // Your implementation
     return result;
   };
   
   const mytoolSchema = z.object({
     // Define your input schema
   });
   
   export { mytoolSchema };

3. Open routes/mcp.js and import the tool:

   import { mytoolTool } from '../tools/mytool.js';
   import { mytoolSchema } from '../tools/mytool.js';

4. Inside the createMcpServer function, register the tool:

   server.registerTool(
     'mytool',
     {
       description: 'Description of your tool',
       inputSchema: mytoolSchema
     },
     mytoolTool
   );

5. Restart the server.

Project Structure

my-mcp-server/
│
├── package.json
├── server.js
├── .env
├── README.md
│
├── tools/
│   ├── calculator.js
│   ├── search.js
│   ├── chat.js
│   └── huggingface.js
│
├── routes/
│   └── mcp.js
│
├── middleware/
│   └── auth.js
│
└── utils/
    └── logger.js

Notes

• The server uses ES modules (type": "module" in package.json)

• The MCP server uses the official @modelcontextprotocol/sdk for HTTP transport

• Error handling is centralized: invalid requests return 400, auth errors return 401, and internal errors return 500 with a JSON error response

• The Hugging Face tool includes timeout and error handling for common API issues

• Logging is done via console with timestamps

License

MIT