Copilot commented on code in PR #11663:
URL: https://github.com/apache/gravitino/pull/11663#discussion_r3417803748
##########
docs/gravitino-mcp-server.md:
##########
@@ -103,9 +103,63 @@ Gravitino MCP server supports the following tools, and you
could export tool by
You could config Gravitino MCP server by arguments, `uv run mcp_server -h`
shows the detailed information.
-| Argument | Description
| Default value | Required | Since version |
-|-------------------|-----------------------------------------------------------------|-----------------------------|----------|---------------|
-| `--metalake` | The Gravitino metalake name.
| none | Yes | 1.0.0 |
-| `--gravitino-uri` | The URI of Gravitino server.
| `http://127.0.0.1:8090` | No | 1.0.0 |
-| `--transport` | Transport protocol type: stdio (local), http (Streamable
HTTP). | `stdio` | No | 1.0.0 |
-| `--mcp-url` | The url of MCP server if using http transport.
| `http://127.0.0.1:8000/mcp` | No | 1.0.0 |
+| Argument | Description
| Default value | Required | Since
version |
+|-------------------|----------------------------------------------------------------------------------|-----------------------------|----------|---------------|
+| `--metalake` | The Gravitino metalake name.
| none | Yes | 1.0.0
|
+| `--gravitino-uri` | The URI of Gravitino server.
| `http://127.0.0.1:8090` | No | 1.0.0
|
+| `--transport` | Transport protocol: stdio (local), http /
streamable-http (Streamable HTTP). | `stdio` | No
| 1.0.0 |
+| `--mcp-url` | The url of MCP server if using http transport.
| `http://127.0.0.1:8000/mcp` | No | 1.0.0
|
Review Comment:
In the configuration table, "url" and "http" should be capitalized as the
standard acronyms (URL/HTTP) for consistency and readability.
##########
docs/gravitino-mcp-server.md:
##########
@@ -103,9 +103,63 @@ Gravitino MCP server supports the following tools, and you
could export tool by
You could config Gravitino MCP server by arguments, `uv run mcp_server -h`
shows the detailed information.
-| Argument | Description
| Default value | Required | Since version |
-|-------------------|-----------------------------------------------------------------|-----------------------------|----------|---------------|
-| `--metalake` | The Gravitino metalake name.
| none | Yes | 1.0.0 |
-| `--gravitino-uri` | The URI of Gravitino server.
| `http://127.0.0.1:8090` | No | 1.0.0 |
-| `--transport` | Transport protocol type: stdio (local), http (Streamable
HTTP). | `stdio` | No | 1.0.0 |
-| `--mcp-url` | The url of MCP server if using http transport.
| `http://127.0.0.1:8000/mcp` | No | 1.0.0 |
+| Argument | Description
| Default value | Required | Since
version |
+|-------------------|----------------------------------------------------------------------------------|-----------------------------|----------|---------------|
+| `--metalake` | The Gravitino metalake name.
| none | Yes | 1.0.0
|
+| `--gravitino-uri` | The URI of Gravitino server.
| `http://127.0.0.1:8090` | No | 1.0.0
|
+| `--transport` | Transport protocol: stdio (local), http /
streamable-http (Streamable HTTP). | `stdio` | No
| 1.0.0 |
+| `--mcp-url` | The url of MCP server if using http transport.
| `http://127.0.0.1:8000/mcp` | No | 1.0.0
|
+| `--token` | OAuth2 Bearer token for Gravitino; or set
`GRAVITINO_TOKEN`. See Authentication. | none (anonymous) | No
| 1.3.0 |
+| `--tls-cert` | PEM certificate to serve the endpoint over HTTPS.
Requires `--tls-key`. | none | No | 1.3.0
|
+| `--tls-key` | PEM private key to serve the endpoint over HTTPS.
Requires `--tls-cert`. | none | No | 1.3.0
|
+
+## 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.
+
+```shell
+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 HTTP endpoint 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).
Review Comment:
The TLS section refers to "the HTTP endpoint", but this doc describes two
endpoints (`--mcp-url` vs `--gravitino-uri`). Clarifying that TLS applies to
the MCP HTTP endpoint (and not the Gravitino URI) will reduce confusion for
readers.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
