One

one-mcp is a lightweight MCP server that lets you manage API tools with semantic search and query them using natural language. It supports multiple transports and provides both a REST API and an MCP interface, making it easy to integrate with clients and tooling while keeping tool embeddings stored locally for fast, offline-ready access.

How to use

You run the MCP server locally and connect through an MCP client that communicates over stdio. The server exposes a set of capabilities you can use from your client, including uploading tools, searching for relevant tools by natural language, inspecting stored tools, and deleting tools. You can also access a REST API for broader integration if you prefer HTTP.

Key workflows you can perform include uploading new API tools, performing semantic searches to find tools that match a description, retrieving statistics about your tool store, and cleaning up stored tools when needed. Tools and their embeddings are saved to disk so you can reload your state on startup.

How to install

Prerequisites: you need Python installed on your system. A virtual environment is recommended to keep dependencies isolated.

# 1) Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

# 2) Install dependencies
pip install -r requirements.txt

3. Run the server with your preferred transport. The server will download the embedding model on first start.

# Dual transport (stdio + HTTP) on port 8003
python server.py --transport stdio,http --port 8003

# HTTP-only mode on port 8003
python server.py --transport http --port 8003

# Stdio-only mode (for MCP clients)
python server.py --transport stdio

If you prefer to run the server directly via a launcher, you can also start it with a standard web server command if you use a frontend like Uvicorn.

Configuration and notes

The server offers these core options and defaults. You can adjust them to fit your environment.

--transport  : stdio, http, or stdio,http  (default: stdio)
--port       : HTTP port number (default: 8000)
--host       : Host to bind (default: 0.0.0.0)
--storage_path: Path to store tool embeddings (default: tool_embeddings.json)

Logs are written to a logs/ directory with rotating file handlers. Tools and embeddings are loaded on startup and saved after any modification, so your state persists across restarts.

MCP configuration example

If you want to integrate with an MCP client, you can declare a local stdio MCP server that runs your python entry point. The following config demonstrates a stdio MCP server using a direct path to the server script.

{
  "mcpServers": {
    "one_mcp": {
      "command": "python",
      "args": [
        "/absolute/path/to/server.py",
        "--transport", "stdio",
        "--storage_path", "tool_embeddings.json"
      ]
    }
  }
}

If you want dual transport (stdio for MCP and HTTP for REST), use the extended config shown here. This enables both MCP and REST API access in a single server instance.

{
  "mcpServers": {
    "one_mcp": {
      "command": "python",
      "args": [
        "/absolute/path/to/server.py",
        "--transport", "stdio,http",
        "--port", "8004",
        "--storage_path", "tool_embeddings.json"
      ]
    }
  }
}

Troubleshooting and tips

If you encounter slow startup or heavy downloads on first run, ensure you have a reliable internet connection for the initial model download. You can monitor logs under the logs/ directory to understand loading progress and any errors that arise.

For troubleshooting connectivity, verify that the host and port you are using match the transport configuration, and confirm the storage_path points to a writable location with sufficient disk space.

Available tools

semantic_search

Find relevant API tools based on descriptive queries using sentence-transformers embeddings.

upload_tools

Add new API tools via JSON payload or file upload to expand the tool store.

delete_tools

Remove specific tools by name, with support for batch deletion.

tool_statistics

Get insights on stored tools including count, model, and storage path.

tool_management

Clear, inspect, or modify the tool store.

multiplex_transport

Support for both MCP stdio and HTTP transports in a single server instance.

persistent_storage

Embeddings and tools are saved to disk and loaded on startup.

structured_logging

Comprehensive logging with rotating file handlers to aid troubleshooting.