README.md

metadata

title: MCEPTION - YOUR MCP AGENCY
emoji: 🏭
colorFrom: purple
colorTo: pink
sdk: gradio
sdk_version: 6.0.0
app_file: app.py
pinned: false
license: mit
short_description: Create and deploy MCP servers using natural language.

🏭 MCEPTION: Your MCP Servers agency

MCEPTION is an MCP (Model Context Protocol) server powered by Gradio that allows generating, testing, and deploying other MCP servers on the fly.

It is an "MCP Server creator of MCP Servers". It enables AI agents (like Claude, ChatGPT, or autonomous smolagents) or human users to create new custom MCP servers and associated Tools, and deploy them instantly to Hugging Face Spaces, thus recursively extending their agent's capabilities.

🌟 Why MCEPTION?

With the widespread adoption of conversational tools and the upcoming era of the generative internet, it becomes essential for companies and administrations to master the information communicated to the public through these AIs.

The MCP protocol, combined with the reasoning capabilities of LLM agents, offers possibilities that are sometimes very difficult to imagine without implementing and testing them. It can also sometimes be disappointing and require numerous settings and adjustments. While the MCP protocol is simple in its design, it requires great care to work really well.

MCEPTION answers a current need: providing organizations with tools to test the impact of the MCP protocol for their activity.

This tool has been designed to leverage the power of the agentic structure calling the MCP (generally through top-tier models), combined with specific LLMs such as GPT OSS or Kimi K2 thinking for reactive coding during the tool design phase.

With MCEPTION, organizations can directly try MCP by attempting, for example, to encapsulate existing APIs, create servers around data files, or even expose directly coded business rules allowing agents to answer deterministically and in a controlled manner on subjects that concern them.

An Intuitive Workflow for Humans and AIs

The tool has been designed to offer an intuitive creation workflow whether for humans or for artificial intelligence agents. In particular, it allows direct testing through a smolagents instance of the generated server's operation, seeing the tools appear and trying them out.

The ideal environment for testing generated MCP servers remains Hugging Chat for Open Source models thanks to the hot reload of MCP servers and their tools.

On the proprietary tools side, the local Claude client works very well, and configurations to integrate tools into Claude are provided by the application.

Thanks Gradio

This project illustrates the impressive capabilities of Gradio to expose MCP services; it articulates perfectly with the Hugging Face Spaces infrastructure, which is very well complemented today by inference services, through the Inference API and Hugging Chat.

🚀 Key Features

• Natural Language Initialization: Simply describe the tool: "I want a tool that gives me the weather in Paris" or "Create a currency converter".
• Intelligent Code Generation: Uses powerful LLMs (GPT OSS, Kimi K2 Thinking) via inference providers routed by HuggingFace (Together AI, Hyperbolic) to write Python code.
• Sandbox & Validation: Check and modify the proposed code before deployment.
• Automated Deployment on HF Spaces: In one click (or tool call), your MCP server is online, hosted for free on Hugging Face Spaces.
• Native MCP Compatible: Generated tools are immediately usable via the MCP protocol natively exposed by Gradio 6.

🛠️ Architecture

📚 Installation & Getting Started

1. Quick Deployment on Hugging Face Spaces

This is the recommended method to use MCEPTION without local installation.

1. Duplicate the Space:

   • Click on the menu (three dots) at the top right of this page, then on "Duplicate this Space".
   • Choose a name for your Space and validate.

2. Token Configuration (Essential):

   • Once the Space is duplicated, go to the Settings tab of your new Space.
   • Scroll down to the Variables and secrets section.
   • Click on New secret.
   • Name: HF_TOKEN
   • Value: Your Hugging Face token (make sure it has WRITE permissions). You can create one here: https://huggingface.co/settings/tokens.

   The Space will restart automatically with your rights, ready to create new Spaces for you!

2. Usage with Claude Desktop

To turn your Claude Desktop into a "tool factory", add the following configuration to your claude_desktop_config.json file:

{
  "mcpServers": {
    "mception": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "http://127.0.0.1:7860/gradio_api/mcp/sse"
      ]
    }
  }
}

Note: If you are using MCEPTION from a public Hugging Face Space, replace the local URL with your Space URL (e.g. https://alihmaou-metamcp-proto.hf.space/gradio_api/mcp/sse).

🤖 Guide for Agents (API)

MCEPTION exposes a suite of MCP tools allowing an autonomous agent to manage the entire tool creation lifecycle.

Typical Workflow

1. Configuration (Optional): step_0_configuration to set the HF user or token if not present in the environment.
2. Design: expert_step1_propose_implementation or step_1_initialisation_and_proposal. The agent submits a description, the server returns a draft_id and a code proposal.
3. Validation: expert_step2_define_logic. The agent confirms the code and dependencies.
4. Deployment: step_3_deployment. The server creates the Hugging Face Space.
5. Usage: The agent receives the config to connect to this new server.

List of Exposed Tools

Tool	Description
step_0_configuration	Configures the environment (HF User, Token, Default Space).
step_1_initialisation_and_proposal	(UI+API) Initializes a project and proposes an implementation via LLM.
step_2_logic_definition	(UI+API) Validates and saves the tool's Python code.
step_3_deployment	(UI+API) Deploys the tool to a Hugging Face Space.
expert_step1_propose_implementation	(Expert API) Generates just the code without UI state (useful for iterating).
expert_step2_define_logic	(Expert API) Defines logic with complex JSON inputs.
util_delete_tool	Deletes a tool from an existing Space.
util_get_tool_code	Retrieves the source code of an existing tool for inspection.

💡 Example Prompt for Claude

Once MCEPTION is connected to Claude, you can tell it:

"Create me a tool that retrieves the current Bitcoin price using the CoinGecko API, and deploy it to my Hugging Face space."

Claude will then:

1. Call step_1 to generate the Python code (requests.get(...)).
2. Ask you for confirmation or call step_2 to validate.
3. Call step_3 to deploy.
4. Give you the config to use this new "Bitcoin Price" tool immediately!

---

Made with ❤️, Python, Gradio and a lot of Agents.