UNITONE MCP Builder

Transform any API into a Model Context Protocol (MCP) server with an intuitive web portal.

Generate MCP servers from OpenAPI/Swagger specs, Postman collections, or API documentation. Make your APIs accessible to AI assistants through natural language interactions.

Built With

Backend: Node.js + TypeScript + Express.js
Frontend: React 18 + Material-UI + Vite
Database: better-sqlite3
MCP SDK: @modelcontextprotocol/sdk v1.20+
Template Engine: Handlebars
Type Safety: TypeScript + Zod

⚠️ Important: Local Development Tool

UNITONE MCP Builder is designed for local development use only.

This is the open source version intended for single-user local development environments, while we welcome contributors!

If you require:

Hosted/managed MCP server generation
Public server deployment with authentication
Extended security features
Enterprise support
Team collaboration features

Please contact the UNITONE team at https://unitone.ai for our enterprise solutions.

Features

🚀 Multiple Input Formats - OpenAPI/Swagger (JSON/YAML), Postman collections, or plain text API docs
🎨 Admin Dashboard - Beautiful Material-UI interface for managing API configurations and MCP servers
🔧 STDIO Transport - Generate servers compatible with any MCP-compatible client
🔐 Authentication Support - Bearer tokens, API keys, and OAuth2 client credentials
🛠️ Auto-generate Tools - Automatically create MCP tools from API endpoints
📦 One-Click Deployment - Deploy and manage servers directly from the dashboard
✅ Type Safe - Full TypeScript support with auto-generated types
🔄 Path Parameters - Automatic path parameter substitution (e.g., /users/{id})
🧩 OpenAPI $ref Resolution - Resolves component references in specifications
📊 Large-Scale APIs - Tested with 200+ endpoint APIs (Microsoft Graph)

Quick Start

Prerequisites

Node.js >= 20.0.0
npm >= 9.0.0

Installation

# Clone the repository
git clone https://github.com/UnitOneAI/MCPBuilder.git
cd MCPBuilder

# Install dependencies
npm install

# Start the application
npm run dev

The dashboard will be available at http://localhost:5173 and the API server at http://localhost:3000.

Admin Portal Guide

Visual walkthrough of creating and deploying an MCP server using the admin portal.

1. MCP Servers Dashboard

Start from the MCP Servers page where you can view all your servers and create new ones.

2. Parse Your API

Provide your API specification using OpenAPI/Swagger, API Documentation, or Postman Collection. The parser will automatically extract endpoints and generate MCP tools.

3. Select Endpoints

Choose which endpoints to expose as MCP tools. The portal shows endpoint details including method, path, description, and parameters. Use the search and filter features for large APIs.

4. Server Generated

Once generation is complete, you'll see the server location and configuration details. The portal provides ready-to-use configuration for your MCP client.

5. Deploy and Run

Deploy your server with one click. The portal handles installation, building, and startup automatically. Monitor server status and manage deployments from the dashboard.

Usage

Option 1: Quick Start with OpenAPI Spec

The fastest way to get started is with an OpenAPI/Swagger specification.

Example - Microsoft Graph Users API:

Navigate to "Create Server" in the dashboard
Click "OpenAPI/Swagger" tab

Paste the spec URL or upload file:

https://raw.githubusercontent.com/microsoftgraph/msgraph-sdk-powershell/dev/openApiDocs/v1.0/Users.yml

Click "Parse & Create Configuration"
Select the endpoints you want (e.g., GET /users, GET /users/{id})
Configure server:
- Name: msgraph-users
- Description: Microsoft Graph Users API
- Auth: OAuth 2
Click "Generate"

Your MCP server will be generated in generated-servers/msgraph-users/.

Available Microsoft Graph APIs:

Users: https://raw.githubusercontent.com/microsoftgraph/msgraph-sdk-powershell/dev/openApiDocs/v1.0/Users.yml
Groups: https://raw.githubusercontent.com/microsoftgraph/msgraph-sdk-powershell/dev/openApiDocs/v1.0/Groups.yml
Mail: https://raw.githubusercontent.com/microsoftgraph/msgraph-sdk-powershell/dev/openApiDocs/v1.0/Mail.yml
Calendar: https://raw.githubusercontent.com/microsoftgraph/msgraph-sdk-powershell/dev/openApiDocs/v1.0/Calendar.yml
View all specs

Option 2: Using Plain Text Documentation

If you don't have an OpenAPI spec, you can paste API documentation or upload file:

GET /users - Get all users
- page (number) - Page number (optional)
- limit (number) - Items per page (optional)

POST /users - Create a new user
- name (string) - User's name (required)
- email (string) - User's email (required)

GET /users/{id} - Get user by ID
- id (string) - User ID (required)

Option 3: Import Postman Collection

Simply paste your exported Postman collection JSON or upload file.

Build and Deploy Your MCP Server

After generation is complete:

Navigate to the "MCP Servers" section in the admin portal
Your server will now be shown with status "Ready"
Click "Deploy" to start the server
If deployment is successful, the status will change from "Ready" to "Running"

The server is now ready to use with any MCP client. Environment variables (API_BASE_URL, API_TOKEN, etc.) are automatically passed from your MCP client configuration - no manual export needed!

Using Generated Servers

All generated servers use STDIO transport, compatible with any MCP-enabled application.

MCP Client Configuration

Configure your MCP-compatible client to use the generated server. Most clients follow a similar configuration pattern:

Example configuration:

{
  "mcpServers": {
    "my-api-server": {
      "command": "node",
      "args": ["/absolute/path/to/generated-servers/my-api-server/dist/index.js"],
      "env": {
        "API_BASE_URL": "https://api.example.com",
        "API_TOKEN": "your_bearer_token_here"
      }
    }
  }
}

Key configuration elements:

command: node
args: Absolute path to dist/index.js in your generated server
env: Environment variables for API configuration

Refer to your MCP client's documentation for specific configuration file locations and format. Generated servers include a .vscode/mcp.json file as a reference.

Note: When using with an MCP client (like Claude Desktop), environment variables are automatically passed from the client configuration. Manual export is only needed for local testing.

Best Practices

Tool Count Recommendations

When creating MCP servers, the number of tools you expose significantly impacts performance and accuracy:

Optimal Range (Recommended): Under 40 tools

Best performance and tool selection accuracy
AI assistants can effectively navigate and choose the right tools
Faster response times and lower resource usage

Warning Range: 40-100 tools

Server will function but may experience reduced performance
Tool selection accuracy may decrease as the AI has more options to evaluate
Consider splitting into multiple focused servers if possible

Critical Range: 100+ tools

Significant performance degradation likely
Poor tool selection accuracy due to overwhelming number of options
Strongly recommended to refactor into multiple servers

Creating Multiple Focused Servers

For large APIs (100+ endpoints), we recommend:

Group by functionality - Organize endpoints into logical domains
- Example: msgraph-users, msgraph-mail, msgraph-calendar
Split by use case - Create servers for specific workflows
- Example: api-read-operations, api-write-operations
Separate by resource type - Divide by primary entities
- Example: api-customers, api-orders, api-inventory

Benefits of multiple servers:

Each server stays under the 40-tool optimal threshold
Improved tool selection accuracy and performance
Users can enable only the servers they need
Easier to maintain and update individual servers
Better error isolation and debugging

Large-Scale API Example

For the Microsoft Graph API (200+ endpoints), instead of one massive server:

# ❌ Avoid: Single server with 200+ tools
msgraph-all-api

# ✅ Recommended: Multiple focused servers
msgraph-users          # 15 tools - User management
msgraph-mail           # 22 tools - Email operations
msgraph-calendar       # 18 tools - Calendar operations
msgraph-groups         # 12 tools - Group management
msgraph-files          # 25 tools - OneDrive operations

The portal will automatically warn you when selecting more than 40 endpoints and provide guidance on creating multiple focused servers.

Project Structure

MCPBuilder/
├── src/
│   ├── server/                      # Express backend API
│   │   ├── routes/                  # API route handlers
│   │   │   ├── apiConfigs.ts        # API configuration endpoints
│   │   │   ├── mcpServers.ts        # MCP server management
│   │   │   ├── deployments.ts       # Server deployment/build
│   │   │   └── parser.ts            # OpenAPI/Postman parsers
│   │   ├── utils/                   # Server utilities
│   │   │   └── logger.ts            # File-based logging
│   │   ├── database.ts              # SQLite database operations
│   │   └── index.ts                 # Server entry point
│   ├── client/                      # React frontend
│   │   ├── components/              # Reusable UI components
│   │   ├── pages/                   # Page components
│   │   ├── services/                # API service layer
│   │   ├── assets/                  # Static assets (images, etc.)
│   │   ├── theme.ts                 # Material-UI theme config
│   │   └── App.tsx                  # Main app component
│   ├── generator/                   # MCP generator core
│   │   ├── McpGenerator.ts          # Code generator
│   │   ├── ApiParser.ts             # API specification parser
│   │   └── handlebars-helpers.ts    # Custom Handlebars helpers
│   ├── templates/                   # Handlebars templates for generated code
│   └── types/                       # Shared TypeScript type definitions
├── generated-servers/               # Generated MCP servers output
├── logs/                            # Server and deployment logs
└── data/                            # SQLite database files

API Endpoints

Core APIs

API Configurations

GET /api/configs - List all API configurations
GET /api/configs/:id - Get API configuration by ID
POST /api/configs - Create API configuration
PUT /api/configs/:id - Update configuration
DELETE /api/configs/:id - Delete configuration

MCP Servers

GET /api/servers - List all MCP servers
GET /api/servers/:id - Get MCP server by ID
POST /api/servers - Create MCP server
PUT /api/servers/:id - Update MCP server
POST /api/servers/:id/generate - Generate server code
DELETE /api/servers/:id - Delete server

Deployments (STDIO Build Only)

GET /api/deployments/server/:serverId - Get deployment status
POST /api/deployments/:serverId/deploy - Build STDIO server
POST /api/deployments/:serverId/stop - Stop deployment process

Parsers

POST /api/parser/openapi - Parse OpenAPI specification (URL or JSON)
POST /api/parser/postman - Parse Postman collection

Development

# Run both backend and frontend
npm run dev

# Run backend only
npm run dev:server

# Run frontend only
npm run dev:client

# Build for production
npm run build

# Type checking
npm run type-check

# Lint code
npm run lint

# Format code
npm run format

Tech Stack

Backend

Node.js + TypeScript
Express.js (REST API server)
better-sqlite3 (embedded database)
Handlebars (template engine)
Zod (schema validation)
Axios (HTTP client)

Frontend

React 18
Material-UI (MUI) + Emotion (CSS-in-JS)
TanStack Query (React Query)
React Router (routing)
React Hook Form (form handling & validation)
Zustand (state management)
Notistack (toast notifications)
Vite + SWC (fast Rust-based build tool)

MCP Integration

@modelcontextprotocol/sdk v1.20+

Troubleshooting

Server won't start

Check that ports 3000 and 5173 are available
Ensure Node.js >= 20.0.0 is installed
Try npm install again

Generated server build fails

Navigate to the generated server directory
Run npm install to ensure dependencies are installed
Check for TypeScript errors with npm run type-check

MCP client can't find the server

Verify the path in your MCP client config is absolute, not relative
Ensure the server is built (npm run build in the generated server directory)
Check that environment variables are set correctly in the config
Restart your MCP client after configuration changes

API authentication errors

Verify your API token/key is valid and not expired
Ensure API_TOKEN or API_KEY is properly set in environment variables
Check your API provider's authentication requirements

Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines.

License

MIT License - see LICENSE file for details.

Resources

Model Context Protocol Docs
OpenAPI Specification
MCP Clients - List of compatible MCP clients

Support

🐛 Bug reports: GitHub Issues
💬 General questions: GitHub Discussions
💬 Community: UNITONE Discord
🔒 Security issues: security@unitone.ai
📧 Contact: UnitOne AI

Built by UnitOne AI | Powered by the Model Context Protocol

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.github/workflows		.github/workflows
docs/images		docs/images
src		src
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.server.json		tsconfig.server.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

UNITONE MCP Builder

Built With

⚠️ Important: Local Development Tool

Table of Contents

Features

Quick Start

Prerequisites

Installation

Admin Portal Guide

1. MCP Servers Dashboard

2. Parse Your API

3. Select Endpoints

4. Server Generated

5. Deploy and Run

Usage

Option 1: Quick Start with OpenAPI Spec

Option 2: Using Plain Text Documentation

Option 3: Import Postman Collection

Build and Deploy Your MCP Server

Using Generated Servers

MCP Client Configuration

Best Practices

Tool Count Recommendations

Creating Multiple Focused Servers

Large-Scale API Example

Project Structure

API Endpoints

Core APIs

Development

Tech Stack

Troubleshooting

Contributing

License

Resources

Support

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages