Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

MCP Server

Run the MariaDB MCP server that is included with MariaDB Shell, so that AI agents and other MCP clients can work with your MariaDB servers, schema projects, and local sandboxes.

MariaDB Shell includes a Model Context Protocol (MCP) server. MCP is an open protocol that lets AI agents, such as coding assistants, call tools that an external server provides. The MariaDB MCP server provides tools to connect to MariaDB servers, inspect schemas, run SQL, manage versioned schema projects, and deploy local sandbox instances.

The MCP server runs inside MariaDB Shell, as the built-in mcp plugin. It uses the shell's own connection handling, credential store, sandbox functions, and SSH tunnels, and it brings its own Python runtime and libraries with the shell, so it needs no separate installation.

The pages in this section describe how to set up, start, and secure the MCP server. For the tools themselves and for example requests, see the MariaDB AI Plugins documentation. The AI Plugins also start the MCP server for you in Claude Code, Codex, OpenCode, and Pi; in these coding agents, you only need to configure its access.

Requirements

  • A MariaDB Shell release package, installed as described in Installation. The release packages include the mcp plugin; a MariaDB Shell built from source doesn't.

  • An MCP client, for example a coding agent or a desktop AI application.

  • For the db tools, a MariaDB server and an account on it. Without a server, the sandbox tools can deploy a local instance.

To check that the plugin is available, print its version:

mariadb-shell -- mcp version

How It Works

You set up the MCP server in two steps, and then let the MCP client start it:

  1. Configure what the server may access. mcp setup stores the database connections the server may open, with their passwords in the credential store, and the local directories it may read and write. Until you do this, the server refuses every connection and every path. See Configuring Access.

  2. Register the server with your MCP client. The client starts mariadb-shell -- mcp start-server as a child process and talks to it over standard input and output, or it connects to a server that you started yourself over HTTP. See Connecting MCP Clients.

The agent never sees the passwords. It lists the configured connections, asks the server to open one, and receives a connection ID that it uses for further calls.

This setup serves one person. To share one server among several users, each authenticated and each with their own connections, use multi-tenant mode. Its users authenticate with an API key or with OAuth2, through Keycloak or by signing in with their MariaDB account.

Tool Groups

The server's tools are organized in function groups. By default, the server provides all of them. To provide only some, use the --functionGroups option of mcp start-server, as described in Starting the MCP Server.

Group
What its tools do

db

List the configured connections, open and close sessions, list schemas and objects, describe objects, and run SQL statements and scripts.

msm

Create and work with versioned schema projects of MariaDB Schema Management, prepare releases, and deploy schemas.

rest

Work with the files of the MariaDB REST Service: generate client SDKs, dump and load REST services and service projects, and load static content. The REST services themselves are managed with REST SQL, which the db tools run.

sandbox

List the server versions that can be deployed, and deploy, start, stop, and delete local sandbox instances. A sandbox's MariaDB REST Daemon starts and stops with it.

migrator

Plan and run a migration from MySQL to MariaDB. Only available on Linux and macOS, after you install the migration tooling with mcp setup.

util

Dump, load, copy, export, and import data as background tasks that a client follows and can cancel.

restd

Set up, start, stop, and delete MariaDB REST Daemons for sandbox instances and other servers.

A multi-tenant server provides only the db group. The msm and rest tools work on files on the developer's own machine, and the util and restd tools run long jobs and local processes on the server's machine, so they are not available on a server that several users reach remotely.

The mcp Global Object

The plugin adds the mcp global object to Python mode, and the mcp object to command line integration:

Python
Command line
Description

mcp.setup()

mcp setup

Configures the connections and directories the server may access, and installs or removes the migration tooling. In multi-tenant mode, also manages the users.

mcp.setup_oauth()

mcp setup-oauth

Configures how a multi-tenant server accepts OAuth2 tokens. See OAuth Authentication.

mcp.setup_keycloak_realm()

mcp setup-keycloak-realm

Prepares a Keycloak realm to issue tokens for the server. See OAuth Authentication.

mcp.start_server()

mcp start-server

Starts the MCP server. It runs in the foreground until it is stopped.

mcp.info()

mcp info

Returns a short description of the plugin.

mcp.version()

mcp version

Returns the version of the plugin.

To show the built-in help, run \? mcp in Python mode, or mariadb-shell -- mcp --help on the command line.

In This Section

Configuring AccessMigration ToolingAutomated SetupStarting the MCP ServerDump and Load ToolsConnecting MCP ClientsMulti-Tenant ModeOAuth AuthenticationRunning in a ContainerSecurity and Session Handling

This page is licensed: GPLv2

Last updated

Was this helpful?