Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dataease/SQLBot/llms.txt

Use this file to discover all available pages before exploring further.

SQLBot runs a dedicated Model Context Protocol (MCP) server on port 8001, separate from the main application. Any MCP-compatible agent or workflow tool can connect to it and ask questions in plain language — SQLBot handles the SQL generation, query execution, and result formatting automatically.

​
How it works

The MCP server exposes six operations, each mapped to a tool that agents can invoke:

mcp_start

Authenticate with username and password. Returns an access_token and a chat_id for the session.

mcp_question

Submit a natural-language question. Returns structured data, SQL, and optionally a chart image.

mcp_ws_list

List the workspaces the authenticated user has access to.

mcp_datasource_list

List the datasources available within a workspace.

mcp_assistant

Ask a question through a specific SQLBot assistant configuration, for use in DataEase and CRM integrations.

get_model_list

Retrieve the list of configured LLM models available in the deployment.
Port 8001 must be reachable from your agent or workflow host. If SQLBot is behind a reverse proxy, make sure you forward this port or expose the MCP path separately.

​
Authentication flow

All MCP operations except mcp_start require a valid access_token. Tokens are short-lived JWTs issued by the same mechanism as the main application.
1

Call mcp_start to obtain a token

POST to /mcp/mcp_start with your SQLBot username and password. The response includes both a token and a fresh chat_id bound to that session.
POST http://<your-host>:8001/mcp/mcp_start
Content-Type: application/json

{
  "username": "admin",
  "password": "SQLBot@123456"
}

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "chat_id": 7356228649239973888
}
2

Discover available workspaces (optional)

If your user belongs to multiple workspaces, call mcp_ws_list to find the oid (workspace ID) you want to query against.
POST http://<your-host>:8001/mcp/mcp_ws_list
Content-Type: application/json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
3

Discover datasources (optional)

Call mcp_datasource_list to get the IDs of datasources available in your workspace. Pass oid to target a specific workspace.
POST http://<your-host>:8001/mcp/mcp_datasource_list
Content-Type: application/json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "oid": "1"
}
The response omits sensitive fields (embedding, table_relation, configuration) and returns a clean list of datasource metadata.
4

Ask a question with mcp_question

Submit your natural-language question. SQLBot selects the right datasource (or uses the one you specify), generates SQL, executes the query, and returns the result.
POST http://<your-host>:8001/mcp/mcp_question
Content-Type: application/json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "chat_id": 7356228649239973888,
  "question": "What were total sales by region last month?",
  "datasource_id": 3,
  "lang": "en",
  "oid": "1",
  "stream": false,
  "return_img": false
}

​
mcp_question parameters

ParameterTypeRequiredDescription
tokenstringYesAccess token from mcp_start.
chat_idintegerYesChat session ID from mcp_start.
questionstringYesNatural-language question to answer.
datasource_idinteger or stringNoPin the query to a specific datasource. If omitted and the session has no datasource set, SQLBot selects automatically.
langstringNoResponse language: zh-CN, zh-TW, en, or ko-KR. Defaults to zh-CN.
oidstringNoWorkspace ID. Effective only when datasource_id is not provided. Defaults to the user’s last-used workspace.
streambooleanNoStream the response as server-sent events. Defaults to true. Set to false to receive a single JSON object.
return_imgbooleanNoInclude a base64 chart image in the response. Defaults to true. Set to false to return data only.
For agent integrations where you want structured, parseable output, use stream: false and return_img: false. This gives you a clean JSON object with the SQL query, result data, and a text summary.

​
Connecting external agents

Claude Desktop supports MCP servers through its configuration file. Add SQLBot as a custom MCP server so Claude can call mcp_start and mcp_question as tools during conversations.Open your Claude Desktop configuration file and add a server entry pointing to the SQLBot MCP endpoint:
{
  "mcpServers": {
    "sqlbot": {
      "url": "http://<your-host>:8001/mcp",
      "type": "http"
    }
  }
}
After restarting Claude Desktop, you will see the SQLBot tools listed in the tool picker. Authenticate by asking Claude to call mcp_start with your credentials, then ask data questions normally.

​
MCP server internals

From backend/main.py, the MCP server is a separate FastAPI application mounted via fastapi-mcp: 
mcp_app = FastAPI()
images_path = settings.MCP_IMAGE_PATH
os.makedirs(images_path, exist_ok=True)
mcp_app.mount("/images", StaticFiles(directory=images_path), name="images")

mcp = FastApiMCP(
    app,
    name="SQLBot MCP Server",
    description="SQLBot MCP Server",
    describe_all_responses=True,
    describe_full_response_schema=True,
    include_operations=[
        "mcp_datasource_list",
        "get_model_list",
        "mcp_question",
        "mcp_start",
        "mcp_assistant",
        "mcp_ws_list"
    ]
)

mcp.mount(mcp_app)
mcp.setup_server()
The images static mount means chart images generated by mcp_question (when return_img: true) are stored on disk and served at http://<your-host>:8001/images/<filename>.
Tokens issued by mcp_start expire according to the ACCESS_TOKEN_EXPIRE_MINUTES setting in your SQLBot configuration. If your agent receives a 403 response, call mcp_start again to refresh the token.

Build docs developers (and LLMs) love

Get started for freeTalk to us