XiYan MCP Service Gateway

A Model Context Protocol (MCP) intermediary supporting natural language interactions with data stores
_{Driven by XiYan-SQL, achieving top-tier performance on public text-to-SQL evaluations}

Capabilities
Operational Overview
System Architecture
Recommended Usage
Tool Interface
Deployment
Via PyPI
Via Smithery.ai
Configuration Details
Language Model Settings
Data Source Configuration
- MySQL Setup
- PostgreSQL Setup
Execution
Client Interface: Claude Desktop
Client Interface: Cline
Client Interface: Goose
Client Interface: Cursor
Troubleshooting
Attribution

Capabilities

🌐 Translate conversational language into executable SQL queries using the XiYanSQL engine.
🤖 Compatibility with standard LLMs (e.g., GPT, Qwen) and the specialized SOTA text-to-SQL model.
💻 Full offline operational support for enhanced data privacy and security.
📝 Native connectivity for MySQL and PostgreSQL systems (with plans for broader dialect support).
🖱️ Ability to enumerate schemas (tables) available as accessible resources.
🔧 Functionality to retrieve sample content from specified tables.

Operational Overview

System Architecture

Integration options are depicted below. The default is Remote Mode, necessitating an API credential for accessing the proprietary xiyanSQL-qwencoder-32B service endpoint (details in Configuration). Conversely, Local Mode offers superior isolation without external key requirements.

Recommended Usage

"Creating an Air-Gapped Data Assistant with MCP + Modelscope API-Inference (Zero Code)"

"XiYan MCP Integration within Modelscope Ecosystem"

Evaluation on MCPBench

The accompanying visualization compares the XiYan MCP server's proficiency against reference MySQL and PostgreSQL MCP implementations on the MCPBench suite. The XiYan Gateway consistently outperforms its counterparts by margins between 2 and 22 percentage points. Comprehensive experimental data is documented in MCPBench and the accompanying paper, "Evaluation Report on MCP Servers".

Tool Interface

The get_data function exposes a natural language interface for data extraction. The service translates user input into an SQL statement, executes it against the database, and returns the resulting set.
The resource path format {dialect}://{table_name} permits fetching a limited volume of sample records from a named table, providing contextual data for the language model.
A base resource path {dialect}:// lists all recognized tables within the connected data source.

Deployment

Via PyPI

Requires Python version 3.11 or newer. Install the stable release using pip:

shell pip install xiyan-mcp-server

For bleeding-edge or source-based installation directly from the repository: shell pip install git+https://github.com/XGenerationLab/xiyan_mcp_server.git

Via Smithery.ai

Refer to the package page: @XGenerationLab/xiyan_mcp_server

Installation status: Partially validated.

Configuration Details

Server operation is governed by a YAML configuration file. A baseline template is available as config_demo.yml:

yaml mcp: transport: "stdio" model: name: "XGenerationLab/XiYanSQL-QwenCoder-32B-2412" key: "" url: "https://api-inference.modelscope.cn/v1/" database: host: "localhost" port: 3306 user: "root" password: "" database: ""

MCP Configuration

Communication protocol can be set to stdio (standard input/output) or sse (Server-Sent Events).

STDIO

Configuration for STDIO: yaml mcp: transport: "stdio"

SSE

Configuration for SSE: yaml mcp: transport: "sse" port: 8000 log_level: "INFO"

The default communication port is 8000. The default logging verbosity is ERROR; setting it to INFO is advised for diagnostics.

Other parameters like debug, host, sse_path, and message_path are available for advanced tuning but usually require no alteration.

Language Model Settings

Name identifies the model to employ, key is the necessary API credential, and url specifies the endpoint. Supported models are summarized below.

Metric	General LLMs (GPT, Qwen-Max)	SOTA Model (Modelscope)	SOTA Model (Dashscope Trial)	On-Premise Model
Purpose	Utility, ease of integration	Peak accuracy, robustness	Peak accuracy, experimental access	Maximum security, self-hosted
Model ID	Official name (e.g., gpt-3.5-turbo, qwen-max)	XGenerationLab/XiYanSQL-QwenCoder-32B-2412	xiyansql-qwencoder-32b	xiyansql-qwencoder-3b
Credential	Provider API key (e.g., OpenAI, Aliyun)	Modelscope API token	Email-gated key	None (Empty String)
Endpoint	Provider's REST URI (e.g., "https://api.openai.com/v1")	https://api-inference.modelscope.cn/v1/	https://xiyan-stream.biz.aliyun.com/service/api/xiyan-sql	http://localhost:5090

General Purpose Models

For standard LLMs like GPT-3.5, configure as follows: yaml model: name: "gpt-3.5-turbo" key: "YOUR KEY " url: "https://api.openai.com/v1" database:

For Alibaba Qwen (e.g., Qwen-max): yaml model: name: "qwen-max" key: "YOUR KEY " url: "https://dashscope.aliyuncs.com/compatible-mode/v1" database:

Specialized Text-to-SQL Model

The recommended cutting-edge model is XiYanSQL-qwencoder-32B (see XiYanSQL Project Page), leading text-to-SQL benchmarks like Bird. Access is available via two avenues:

(1) Modelscope Access

Requires an API-Inference key from Modelscope (see Modelscope Docs). yaml model: name: "XGenerationLab/XiYanSQL-QwenCoder-32B-2412" key: "" url: "https://api-inference.modelscope.cn/v1/"

(2) Dashscope Trial Access

This model version is hosted on Alibaba Cloud DashScope for evaluation purposes. To obtain a trial key, email the following details to godot.lzl@alibaba-inc.com: yaml name: "YOUR NAME", email: "YOUR EMAIL", organization: "your college or Company or Organization"

The provided key is subject to a one-month or 200-query limit. yaml model: name: "xiyansql-qwencoder-32b" key: "KEY" url: "https://xiyan-stream.biz.aliyun.com/service/api/xiyan-sql"

Warning: This Dashscope service is intended for pilot use only.

(3) Local Version

Deploy the XiYanSQL-qwencoder-32B model on your own infrastructure. Consult Local Model Documentation for deployment instructions.

Data Source Configuration

Connection parameters (host, port, user, password, database) define access to your data repositories. Support currently includes MySQL and PostgreSQL (with expansion planned).

MySQL

yaml database: host: "localhost" port: 3306 user: "root" password: "" database: ""

PostgreSQL

Step 1: Install necessary Python driver: bash pip install psycopg2

Step 2: Configure the YAML file, explicitly setting the dialect: yaml database: dialect: "postgresql" host: "localhost" port: 5432 user: "" password: "" database: ""

Note: Ensure dialect is set to postgresql for this database type.

Execution

Server Launch

If operating in sse mode, initiate the server from a terminal using: shell YML=path/to/yml python -m xiyan_mcp_server

This exposes status/communication on http://localhost:8000/sse (unless custom host/port specified).

For stdio transport, the command is typically managed directly by the consuming MCP application. However, it can be executed standalone for testing purposes.

Client Setting

Claude Desktop

Integrate into the Claude Desktop configuration file (refer to Example Image):

{ "mcpServers": { "xiyan-mcp-server": { "command": "/xxx/python", "args": [ "-m", "xiyan_mcp_server" ], "env": { "YML": "PATH/TO/YML" } } } }

Crucial Note: The path specified for the Python executable (/xxx/python) must be the absolute location (obtainable via which python). This strict path requirement applies across all client integration examples.

Claude Desktop currently does not support SSE transport protocol.

Cline

Configuration structure mirrors the Claude Desktop setup specified above.

Goose

For stdio mode, include the execution string in your configuration (see Goose Example): shell env YML=path/to/yml /xxx/python -m xiyan_mcp_server

For sse mode, set the client Type to SSE and the endpoint to http://127.0.0.1:8000/sse.

Cursor

Use a similar structure for stdio:

{ "mcpServers": { "xiyan-mcp-server": { "command": "/xxx/python", "args": [ "-m", "xiyan_mcp_server" ], "env": { "YML": "path/to/yml" } } } }

For sse in Cursor:

{ "mcpServers": { "xiyan-mcp-server_1": { "url": "http://localhost:8000/sse" } } }

Witsy

Specify the execution command: shell /xxx/python -m xiyan_mcp_server

And define an environment variable where the key is YML and the value is the path to your configuration file. Ref Witsy Configuration Reference

Contact us:

We welcome inquiries regarding our ongoing research or deployed solutions.

Contact Information:

Yifu Liu, zhencang.lyf@alibaba-inc.com

Join Our DingTalk Group

DingTalk Community Channel

Attribution

If this project proves beneficial in your work, citing our research is appreciated. bibtex @article{XiYanSQL, title={XiYan-SQL: A Novel Multi-Generator Framework For Text-to-SQL}, author={Yifu Liu and Yin Zhu and Yingqi Gao and Zhiling Luo and Xiaoxia Li and Xiaorong Shi and Yuntao Hong and Jinyang Gao and Yu Li and Bolin Ding and Jingren Zhou}, year={2025}, eprint={2507.04701}, archivePrefix={arXiv}, primaryClass={cs.CL}, url={https://arxiv.org/abs/2507.04701}, }

bibtex @article{xiyansql_pre, title={A Preview of XiYan-SQL: A Multi-Generator Ensemble Framework for Text-to-SQL}, author={Yingqi Gao and Yifu Liu and Xiaoxia Li and Xiaorong Shi and Yin Zhu and Yiming Wang and Shiqi Li and Wei Li and Yuntao Hong and Zhiling Luo and Jinyang Gao and Liyu Mou and Yu Li}, year={2024}, journal={arXiv preprint arXiv:2411.08599}, url={https://arxiv.org/abs/2411.08599}, primaryClass={cs.AI} }

XHR (XMLHttpRequest) is a JavaScript API enabling asynchronous HTTP communication between a browser application and a remote server following initial page load, forming the backbone of Ajax. Historically, server interaction relied solely on page navigation via forms or standard links. The core concept originated with Microsoft Outlook developers around 2000, first appearing in IE 5 (1999) using proprietary ActiveXObject identifiers. By IE 7 (2006), the standardized XMLHttpRequest identifier became universally adopted across major browser engines (Gecko, Safari, Opera).

The W3C formalized the specification in 2006, with Level 2 additions in 2008 introducing features like event monitoring, cross-origin request handling, and byte stream management, before being merged back into the main standard by 2011. Development responsibility transitioned to WHATWG in 2012, maintaining the living document via Web IDL.

Standard usage involves object instantiation, configuring the request type, URI, and async mode via the open() method, setting up state change handlers for asynchronous operations, executing the transmission with send(), and processing the response, typically found in responseText upon reaching state 4 (completion). Advanced controls include setting custom request headers, uploading data via the send() payload, automatic JSON parsing, streaming response handling, and request cancellation or timeout settings.

Cross-domain communication initially posed a significant security challenge, limiting early web applications.

xiyan-mcp-service-gateway

Author

XGenerationLab

Quick Info

Actions

Tags