Skip to main content

MCP server

The MCP server lets AI agents browse and manage Gravitino metadata through the Model Context Protocol. Agents call tools such as get_list_of_catalogs or get_table_metadata_details, and the server turns each call into a request to the Gravitino server on behalf of the agent's user, so Gravitino authorizes every call exactly as it would the same request from the UI or the API.

The Helm chart installs the MCP server alongside the Gravitino server by default, and the ingress from Install publishes it at /mcp on the UI hostname.

Quick start​

The commands use the shell variables set in step 1 of Install.

  1. Check that the server is running. The MCP pod starts after the Gravitino server answers, so it can sit in its init container for a minute after an install.

    Check the MCP pod
    kubectl -n "$NAMESPACE" get pods | grep mcp

    The pod should show Running with all containers ready.

  2. Point the agent at the endpoint. The address is https://{ui_hostname}/mcp. Each request carries the agent user's own credentials, which with the chart's default basic authenticator are a user name and password in a Basic header. Taking Cursor as an example:

    ~/.cursor/mcp.json
    {
      "mcpServers": {
        "gravitino": {
          "url": "https://{ui_hostname}/mcp",
          "headers": {
            "Authorization": "Basic {base64_user_password}"
          }
        }
      }
    }

    Produce the header value with printf '%s' '{username}:{password}' | base64. Other agents take the same URL and header in their own configuration format.

  3. Ask for something the user can see. A request such as "list the catalogs in metalake {metalake}" should return the catalogs that user is entitled to. A user with no access to the metalake gets an authorization error back from Gravitino.

What an agent can do​

Agents mostly read: catalogs, schemas, tables, topics, filesets, models, tags, policies, statistics, and jobs. The tools that change anything are limited to attaching and removing tags and policies, and running and cancelling jobs. MCP tools lists every tool, how a call chooses its metalake, and how to offer an agent only some of the tools.

Identity​

The server forwards each request's Authorization header to Gravitino unchanged, so every agent acts as its own user and concurrent sessions from different users stay apart. Send Basic credentials under the basic authenticator, or a Bearer token from your identity provider under oauth. Gravitino makes every access decision; the MCP server makes none of its own.

A request without an Authorization header is rejected unless a service identity is configured, in which case it acts as that one identity. MCP server in the Helm configuration covers the service identity and the other server settings.

Audit log​

The server records every tool call, with the user and the outcome, in a log of its own. See MCP server tool calls.

Last updated on