MCP Server

Introduction

Gravitino MCP server provides the ability to manage Gravitino metadata for LLM.

Requirements

1. Python 3.10+
2. uv is installed. Install uv by following the official guide.

Usage

1. Clone the code from GitHub, and change to mcp-server directory
2. Create virtual environment, uv venv
3. Install the required Python packages. uv pip install -e .
4. Add Gravitino MCP server to corresponding LLM tools. Take cursor for example, edit ~/.cursor/mcp.json, use following configuration for local Gravitino MCP server:

{
  "mcpServers": {
    "gravitino": {
      "command": "uv",
      "args": [
        "--directory",
        "$path/mcp-server",
        "run",
        "mcp_server",
        "--metalake",
        "test",
        "--gravitino-uri",
        "http://127.0.0.1:8090"
      ]
    }
  }
}

Or start an HTTP MCP server by uv run mcp_server --metalake test --gravitino-uri http://127.0.0.1:8090 --transport http --mcp-url http://localhost:8000/mcp, and use the configuration:

{
  "mcpServers": {
    "gravitino": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Docker Instructions

You could start Gravitino MCP server by Docker image, docker run -p 8000:8000 --network=host apache/gravitino-mcp-server:latest --metalake test --transport http --mcp-url http://0.0.0.0:8000/mcp --gravitino-uri http://127.0.0.1:8090. Please note that the MCP server in Docker container doesn't support stdio transport mode.

Supported Tools

Gravitino MCP server supports the following tools, and you could export tool by tag.

Tool name	Description	Tag
get_list_of_catalogs	Retrieve a list of all catalogs in the system.	catalog
create_catalog	Create a new catalog.	catalog
alter_catalog	Alter an existing catalog.	catalog
drop_catalog	Drop a catalog.	catalog
set_catalog_in_use	Enable or disable a catalog.	catalog
get_list_of_schemas	Retrieve a list of schemas belonging to a specific catalog.	schema
create_schema	Create a new schema.	schema
alter_schema	Alter an existing schema.	schema
drop_schema	Drop a schema.	schema
get_list_of_tables	Retrieve a list of tables within a specific catalog and schema.	table
get_table_metadata_details	Retrieve comprehensive metadata details for a specific table.	table
create_table	Create a new table.	table
alter_table	Alter an existing table.	table
drop_table	Drop a table.	table
list_of_models	Retrieve a list of models within a specific catalog and schema.	model
load_model	Retrieve comprehensive metadata details for a specific model.	model
list_model_versions	Retrieve a list of versions for a specific model.	model
load_model_version	Retrieve comprehensive metadata details for a specific model version.	model
load_model_version_by_alias	Retrieve comprehensive metadata details for a specific model version by alias.	model
register_model	Register a new model.	model
delete_model	Delete a model.	model
link_model_version	Link a new version to a model.	model
delete_model_version	Delete a model version.	model
delete_model_version_by_alias	Delete a model version by one of its aliases.	model
alter_model	Alter an existing model.	model
alter_model_version	Alter a model version.	model
alter_model_version_by_alias	Alter a model version by one of its aliases.	model
metadata_type_to_fullname_formats	Retrieve the metadata type to fullname formats mapping.	metadata
list_of_topics	Retrieve a list of topics within a specific catalog and schema.	topic
load_topic	Retrieve comprehensive metadata details for a specific topic.	topic
create_topic	Create a new topic.	topic
alter_topic	Alter an existing topic.	topic
delete_topic	Delete a topic.	topic
list_of_filesets	Retrieve a list of filesets within a specific catalog and schema.	fileset
load_fileset	Retrieve comprehensive metadata details for a specific fileset.	fileset
list_files_in_fileset	Retrieve a list of files within a specific fileset.	fileset
create_fileset	Create a new fileset.	fileset
alter_fileset	Alter an existing fileset.	fileset
drop_fileset	Drop a fileset.	fileset
list_of_jobs	Retrieve a list of jobs	job
get_job_by_id	Retrieve a job by its ID.	job
list_of_job_templates	Retrieve a list of job templates.	job
get_job_template_by_name	Retrieve a job template by its name.	job
run_job	Run a job with the specified parameters.	job
cancel_job	Cancel a running job by its ID.	job
get_tag_by_name	Retrieve a tag by its name.	tag
list_of_tags	Retrieve a list of tags.	tag
list_tags_for_metadata	Retrieve a list of tags associated with a specific metadata item.	tag
list_metadata_by_tag	Retrieve a list of metadata items associated with a specific tag.	tag
associate_tag_with_metadata	Associate tags with a specific metadata item.	tag
disassociate_tag_from_metadata	Disassociate tags from a specific metadata item.	tag
create_tag	Create a new tag.	tag
alter_tag	Alter an existing tag.	tag
delete_tag	Delete a tag.	tag
list_statistics_for_metadata	Retrieve a list of statistics associated with a specific metadata item.	statistics
list_statistics_for_partition	Retrieve a list of statistics associated with a specific partition.	statistics
get_list_of_policies	Retrieve a list of policies in the system.	policy
get_policy_detail_information	Retrieve detailed information for a specific policy by policy name.	policy
list_policies_for_metadata	List all policies associated with a specific metadata item.	policy
list_metadata_by_policy	List all metadata items associated with a specific policy.	policy
get_policy_for_metadata	Get a policy associated with a specific metadata item.	policy
list_of_partitions	Retrieve partitions for a table. Only for catalogs with a partition API.	partition
get_partition	Retrieve a partition's metadata. Only for catalogs with a partition API.	partition
list_of_views	Retrieve a list of views for a schema. Only for catalogs supporting views.	view
load_view	Retrieve a view's metadata. Only for catalogs supporting views.	view

Configuration

You could config Gravitino MCP server by arguments, uv run mcp_server -h shows the detailed information.

Argument	Description	Default value	Required
--metalake	The Gravitino metalake name.	none	Yes
--gravitino-uri	The URI of Gravitino server.	http://127.0.0.1:8090	No
--transport	Transport protocol: stdio (local), http / streamable-http (Streamable HTTP).	stdio	No
--mcp-url	The URL of MCP server if using HTTP transport.	http://127.0.0.1:8000/mcp	No
--token	OAuth2 Bearer token for Gravitino; or set GRAVITINO_TOKEN. See Authentication.	none (anonymous)	No
--tls-cert	PEM certificate to serve the endpoint over HTTPS. Requires --tls-key.	none	No
--tls-key	PEM private key to serve the endpoint over HTTPS. Requires --tls-cert.	none	No

Authentication

By default the MCP server talks to Gravitino anonymously. There are two ways to attach an identity, depending on the transport.

Static startup token (stdio and HTTP)

Pass --token (or set the GRAVITINO_TOKEN environment variable) to authenticate the server with a static OAuth2 Bearer token. The value is treated as a Bearer token and sent as Authorization: Bearer <token>. The token is masked in the server's log output.

uv run mcp_server --metalake test --gravitino-uri http://127.0.0.1:8090 --token <your-token>
# or
export GRAVITINO_TOKEN=<your-token>
uv run mcp_server --metalake test --gravitino-uri http://127.0.0.1:8090

In stdio mode this token is used for every request. In HTTP mode it is only the fallback, used when an incoming request does not carry its own Authorization header.

Per-request identity (HTTP)

When the server runs with HTTP transport, the Authorization header of each incoming MCP request is forwarded verbatim to Gravitino. The scheme is preserved, so OAuth2 (Bearer), Gravitino simple authentication (Basic <base64(user:dummy)>) and others all work. This keeps concurrent sessions from different principals isolated — one principal's identity never leaks into another's calls — and lets Gravitino enforce authorization per caller. The per-request header takes priority over the static --token.

Authorization itself is always enforced by Gravitino: the MCP server forwards the identity but does not make access-control decisions of its own.

Serving over HTTPS (TLS)

To serve the MCP HTTP endpoint (the --mcp-url, not the --gravitino-uri) over TLS, provide both --tls-cert and --tls-key and use an https:// --mcp-url. The certificate and key must be provided together, and the URL scheme must match the TLS setting (an https:// URL without a cert/key, or a cert/key behind an http:// URL, is rejected at startup).

uv run mcp_server --metalake test --gravitino-uri http://127.0.0.1:8090 \
  --transport streamable-http --mcp-url https://localhost:8000/mcp \
  --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem

Audit Logging

Every tool invocation is recorded as one structured JSON line in gravitino-mcp-audit.log (written to the server's working directory). Each record is attributed to the principal derived from the request's Authorization header.

Field	Description
timestamp	UTC ISO-8601 time of the call.
principal	Caller identity: username for Basic simple auth, bearer:<first-8-chars> for a Bearer token, or anonymous when no identity is present.
tool	Name of the invoked MCP tool.
outcome	allow for successful calls, deny for failed ones. deny is emitted for any tool-call exception (authorization denial being the common case); inspect error_type to disambiguate.
error_type	Exception class name, present only when outcome is deny.

Example record:

{"timestamp": "2026-06-16T03:21:09.123456+00:00", "principal": "alice", "tool": "get_list_of_catalogs", "outcome": "allow"}