Docs: MCP Server — v2.0.x-SNAPSHOT OAuth, security, tools reference, and connection guide updates by kiran1287 · Pull Request #368 · open-metadata/docs-om

kiran1287 · 2026-08-13T05:17:02Z

Summary

oauth.mdx: Added Dynamic Client Registration flow (RFC 7591), discovery endpoints table, token lifetimes (10min access / 30-day refresh), rate limits, CORS config, and SAML SSO provider card
security.mdx: New page covering PKCE (SHA-256), public client handling, RBAC/ABAC enforcement per tool call, audit trail, secrets-in-logs behavior, and session revocation
connect.mdx: Updated server version 0.11.2 to 1.1.0, protocol 2024-11-05 to 2025-03-26 (Streamable HTTP), removed fake create-greeting prompt that does not exist, updated tools/list sample response to reflect 24-tool server
reference.mdx: Added 5 missing context tools (get_user_context, get_persona_context, get_asset_context, find_context, get_knowledge_content); added Data Quality entity types to search_metadata; added similarityScore note; added extension/custom properties note to get_entity_details; added Read/Write type labels and Context category to tools table
semantic-search.mdx: Corrected OpenSearch-only claim — Elasticsearch vector search is also supported

All changes are scoped to v2.0.x-SNAPSHOT only. No changes to v1.12.x or v1.13.x.

Test plan

Verify oauth.mdx renders correctly with SAML card and new sections
Verify security.mdx appears in sidebar under MCP section
Verify connect.mdx version numbers and prompts/list response are correct
Verify reference.mdx Context section with 5 new tools renders and anchors work
Verify semantic-search.mdx comparison table shows Elasticsearch support

…nection guide updates - oauth.mdx: Add Dynamic Client Registration flow, discovery endpoints, token lifetimes, rate limits, CORS config, SAML card - security.mdx: New page covering PKCE, public client handling, RBAC enforcement, audit trail, secrets in logs, session revocation - connect.mdx: Bump version 0.11.2→1.1.0, protocol 2024-11-05→2025-03-26 (Streamable HTTP), remove fake create-greeting prompt, update tools/list sample response - reference.mdx: Add 5 missing context tools (get_user_context, get_persona_context, get_asset_context, find_context, get_knowledge_content), add Data Quality entity types to search_metadata, add similarityScore note, add extension/custom properties note to get_entity_details, add Read/Write type labels - semantic-search.mdx: Fix OpenSearch-only claim — Elasticsearch vector search is also supported

mintlify · 2026-08-13T05:17:05Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
openmetadata	🟢 Ready	View Preview	Aug 13, 2026, 5:21 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

The security.mdx page was never added to docs.json navigation, leaving it orphaned.

ayush-shah · 2026-08-13T14:02:10Z

+
+## Allowed Origins (CORS)
+
+By default, the MCP Server allows requests from all origins. For self-hosted deployments, administrators can restrict allowed origins by configuring `mcpConfiguration.allowedOrigins` in the OpenMetadata server configuration file.


[P1] Correct the CORS default and configuration surface. allowedOrigins is loaded from database-backed MCP settings, not the server configuration file, and the transport sends CORS headers only when the request origin exactly matches an allowed origin. There is no all-origins default. Point readers to the MCP settings API or UI and an explicit allowlist.

Fixed in 0362138. Corrected the default: it's a fixed localhost allowlist (localhost:3000, :8585, :9090), not all-origins — verified against mcpConfiguration.json in openmetadata-spec. Storage is DB-backed via SettingsType.MCP_CONFIGURATION, editable via GET/PUT /api/v1/system/mcp/config (admin-only); confirmed the MCP app's settings UI doesn't currently expose this field, so the docs now point to the API only. Matching is exact-origin (allowedOrigins.contains(origin)), no wildcard/prefix — now stated explicitly.

ayush-shah · 2026-08-13T14:02:11Z

 }
 ```

+## Context


[P1] Regenerate the Context reference from the tool manifest. The new entries do not match shipped schemas: get_persona_context reads personaName, not persona; get_knowledge_content requires entityType and fqn; and find_context semantically searches company knowledge rather than keyword-searching asset or persona memories. The documented requests will behave differently or fail. Regenerate the parameter tables and examples from tools.json.

Fixed in 0362138. Regenerated all 5 tool parameter tables and examples against tools.json on origin/main — corrected get_persona_context to personaName, added the required entityType/fqn params to get_knowledge_content, and reworded find_context as a semantic search over company knowledge (glossary term definitions, metric definitions, Context Center articles) that returns candidate assets, not a keyword search over asset/persona memories.

ayush-shah · 2026-08-13T14:02:13Z

+
+Only origins on the allowlist will receive a valid `Access-Control-Allow-Origin` response header. This is relevant for browser-based MCP clients or custom integrations that call the MCP endpoint directly from a web page.
+
+For a full breakdown of the security model — PKCE details, public client handling, RBAC enforcement, audit trail, and secrets management — see the [MCP Server Security](/v2.0.x-SNAPSHOT/how-to-guides/mcp/security) page.


[P1] Do not link the deleted security page. This PR deletes security.mdx, so this link is a 404 and the current documentation-link check fails. It also directs readers to an active-session management screen that the current implementation does not expose. Remove the link and describe the supported OAuth revocation workflow, or restore a corrected page.

Fixed in 0362138. Removed the link to the deleted security.mdx page and replaced it with a new 'Revoking Access' section describing the actual OAuth 2.0 Token Revocation flow (RFC 7009): POST {baseUrl}/mcp/revoke, with revocation_endpoint verified as genuinely advertised in the OAuth discovery document (OAuthWellKnownFilter). Kept the existing pointer to session management under the Token Management section for user-level revocation.

ayush-shah · 2026-08-13T14:02:14Z

+| Endpoint | Purpose |
+|----------|---------|
+| `GET /.well-known/oauth-authorization-server` | OAuth 2.0 authorization server metadata (RFC 8414) |
+| `GET /.well-known/openid-configuration` | OpenID Connect discovery (for OIDC-aware clients) |


[P2] Do not label the OAuth metadata alias as OIDC discovery. /.well-known/openid-configuration is routed to the OAuth authorization-server metadata handler; it does not expose an OIDC discovery document. Label it as an OAuth metadata compatibility alias, or remove it from this table.

Fixed in 0362138. Verified in OAuthWellKnownFilter that both /.well-known/oauth-authorization-server and /.well-known/openid-configuration route to the same handleMetadata handler and serialize the identical RFC 8414 OAuthMetadata object — no OIDC-specific fields (userinfo_endpoint, jwks_uri, etc.) are added. Relabeled the row as an OAuth metadata compatibility alias rather than true OIDC discovery.

ayush-shah · 2026-08-13T14:02:16Z

 ```

+<Note>
+Results include a `similarityScore` field (0.0–1.0) for each entity when semantic ranking is active, indicating how closely the result matches your query. Higher scores indicate stronger relevance.


[P2] Do not promise a normalized semantic-only similarity score. search_metadata forwards the backend _score whenever it is present; current tests include 12.5 and 8.0. It is neither guaranteed 0–1 nor restricted to semantic ranking. Describe it as an opaque backend score, or move the claim to a tool with that contract.

Fixed in 0362138. Verified in SearchMetadataTool.java that similarityScore is a direct passthrough of the backend's raw _score field with no normalization applied. Rewrote the note to describe it as the backend's opaque relevance score (not a 0.0-1.0 normalized value), meaningful only as relative ordering within a single result set.

ayush-shah · 2026-08-13T14:02:18Z

 <Info>

-Semantic Search requires **OpenSearch** as the search backend and must be [enabled in your deployment
+Semantic Search requires **OpenSearch or Elasticsearch** as the search backend and must be [enabled in your deployment


[P2] Align the linked deployment guide. This page now says Elasticsearch supports semantic search, but the linked deployment guide still says Elasticsearch is not supported throughout prerequisites and troubleshooting. Update that guide in this change, or keep this page OpenSearch-only, so deployment instructions do not conflict.

Fixed in 0362138. Verified both ElasticSearchVectorService and OpenSearchVectorService implement KNN vector search, so core semantic search works on both backends; the hybrid keyword+semantic pipeline (hybrid-rrf) exists only in the OpenSearch client. Updated deployment/semantic-search.mdx (prerequisites, Info callout, troubleshooting) to match this page's Elasticsearch support claim and call out the hybrid-pipeline caveat, so the two pages no longer contradict each other.

Corrects the CORS defaults and settings surface, relabels the OIDC discovery alias, removes the dead security.mdx link in favor of a Revoking Access section, regenerates the Context tool parameter tables from the actual tool schemas, describes similarityScore as an opaque backend score, and reconciles Elasticsearch semantic search support between the MCP docs and the deployment guide.

Databricks doesn't connect to an MCP server the way Claude or Cursor do; an admin registers it once as a Unity Catalog HTTP connection, then as a governed MCP Service in Unity Catalog, and grants EXECUTE to the callers who need it. Documents that flow end to end (UI and REST API), including the per-user OAuth U2M login step, and registers the page in docs.json navigation. Addresses open-metadata/OpenMetadata#27937.

…MCP guide Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

…o fix/mcp-oauth-security-docs

ayush-shah · 2026-08-18T11:31:01Z

+7. Click **Create** to save the connection.
+
+<Tip>
+If your OpenMetadata deployment authenticates with OAuth 2.0 instead of a PAT, use **OAuth M2M** (shared service-principal credentials) or **OAuth U2M** (per-user login) as the authentication type instead of Bearer token. See [OAuth 2.0 Authentication](/v2.0.x-SNAPSHOT/how-to-guides/mcp/oauth) for the values OpenMetadata expects.


[P1] Do not advertise unsupported OAuth M2M\n\nThe new Databricks setup tells users to use OAuth M2M (client credentials). The shipped MCP OAuth flow does not accept grant_type=client_credentials: the integration test sends that request and expects HTTP 400, while the server advertises authorization_code and refresh_token grant types. A reader choosing OAuth M2M therefore cannot authenticate the Databricks connection. Remove this option or document a grant flow that the server actually supports.\n\n

Fixed in 7eeacba. Verified in McpOAuthIT.java: the token endpoint explicitly rejects grant_type=client_credentials with a 400, and app registration only accepts authorization_code/refresh_token. Removed OAuth M2M from the auth type Tip and the Prerequisites bullet; kept Bearer token (PAT) as the shared non-interactive credential and OAuth U2M for per-user login, both of which the server actually supports.

Verified in McpOAuthIT.java: the MCP OAuth token endpoint explicitly rejects grant_type=client_credentials with a 400, and registration only accepts authorization_code/refresh_token grant types. OAuth M2M (which requires client_credentials) was never a working option for the Databricks Unity Catalog HTTP connection. Removed it from the auth type Tip and the Prerequisites bullet, keeping Bearer token (PAT) as the shared non-interactive credential and OAuth U2M for per-user login, both of which the server actually supports.

ayush-shah · 2026-08-21T04:22:23Z

[P1] Document client authentication for token revocation

The new example at oauth.mdx:180-182 sends only token and token_type_hint. The live revocation handler advertises client_secret_basic and client_secret_post and authenticates the registered client before processing the token, so this copy-paste request returns invalid_client. Document HTTP Basic or form client_id/client_secret authentication.

[P2] Reconcile the OAuth and JWT setup instructions

connect.mdx:16-32 says OAuth is recommended or JWT is supported, then says the server requires JWT and shows only JWT setup. Document the supported OAuth setup, or state clearly that JWT is the only supported option.

[P2] Use the runtime vector alias in troubleshooting

The newly broadened cross-backend guidance still tells users to check vector_search_index at deployment/semantic-search.mdx:41, line 263, and mcp/semantic-search.mdx:156. Runtime resolves dataAssetEmbeddings or <clusterAlias>_dataAssetEmbeddings (VectorIndexService); replace all three references.

[P2] Correct the Databricks navigation path

databricks.mdx:31 says Catalog > External Data > Connections, while the current Databricks UI uses Catalog > Connections. Update the path so readers can find the connection-creation screen.

Existing feedback follow-up (same roots, not duplicate findings): the CORS paragraph at oauth.mdx:174-178 still incorrectly says allowedOrigins is not exposed in the UI; McpApplicationConfiguration exposes it. The active-session-management claims at oauth.mdx:95,161,182 remain unsupported and should be removed or replaced. The addressed Context and semantic-search threads still need re-review/resolution.

… docs

kiran1287 self-assigned this Aug 13, 2026

kiran1287 linked an issue Aug 13, 2026 that may be closed by this pull request

Docs: MCP Server documentation gaps — v2.0.x-SNAPSHOT #369

Open

5 tasks

mintlify Bot deployed to staging August 13, 2026 05:21 View deployment

Docs: Remove unreferenced MCP security page for v2.0.x-SNAPSHOT

e0671a6

The security.mdx page was never added to docs.json navigation, leaving it orphaned.

mintlify Bot deployed to staging August 13, 2026 13:07 View deployment

ayush-shah reviewed Aug 13, 2026

View reviewed changes

mintlify Bot deployed to staging August 14, 2026 10:44 View deployment

Merge branch 'main' into fix/mcp-oauth-security-docs

35ff90a

mintlify Bot deployed to staging August 14, 2026 19:15 View deployment

kiran1287 added 2 commits August 18, 2026 11:38

Merge branch 'main' into fix/mcp-oauth-security-docs

e8cf221

mintlify Bot deployed to staging August 18, 2026 06:12 View deployment

mintlify Bot deployed to staging August 18, 2026 06:15 View deployment

kiran1287 and others added 2 commits August 18, 2026 12:52

Docs: Combine AI Gateway navigation into a single step in Databricks …

8aec993

…MCP guide Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Merge remote-tracking branch 'origin/fix/mcp-oauth-security-docs' int…

5d6678d

…o fix/mcp-oauth-security-docs

mintlify Bot deployed to staging August 18, 2026 07:26 View deployment

ayush-shah reviewed Aug 18, 2026

View reviewed changes

mintlify Bot deployed to staging August 19, 2026 05:09 View deployment

Merge branch 'main' into fix/mcp-oauth-security-docs

c6310fb

mintlify Bot deployed to staging August 19, 2026 05:13 View deployment

Merge branch 'main' into fix/mcp-oauth-security-docs

129c832

mintlify Bot deployed to staging August 19, 2026 11:36 View deployment

Merge branch 'main' into fix/mcp-oauth-security-docs

0f68a43

mintlify Bot deployed to staging August 20, 2026 07:52 View deployment

Merge branch 'main' into fix/mcp-oauth-security-docs

053e286

mintlify Bot deployed to staging August 20, 2026 11:51 View deployment

Merge branch 'main' into fix/mcp-oauth-security-docs

9785f09

mintlify Bot deployed to staging August 20, 2026 15:11 View deployment

Docs: Fix MCP OAuth revocation, CORS, and reconcile auth/vector-index…

b834828

… docs

mintlify Bot deployed to staging August 21, 2026 06:13 View deployment

Merge branch 'main' into fix/mcp-oauth-security-docs

2e56a93

mintlify Bot deployed to staging August 21, 2026 18:07 View deployment


		## Allowed Origins (CORS)

		By default, the MCP Server allows requests from all origins. For self-hosted deployments, administrators can restrict allowed origins by configuring `mcpConfiguration.allowedOrigins` in the OpenMetadata server configuration file.


		Only origins on the allowlist will receive a valid `Access-Control-Allow-Origin` response header. This is relevant for browser-based MCP clients or custom integrations that call the MCP endpoint directly from a web page.

		For a full breakdown of the security model — PKCE details, public client handling, RBAC enforcement, audit trail, and secrets management — see the [MCP Server Security](/v2.0.x-SNAPSHOT/how-to-guides/mcp/security) page.

Uh oh!

Conversation

kiran1287 commented Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

mintlify Bot commented Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ayush-shah commented Aug 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kiran1287 commented Aug 13, 2026 •

edited

Loading

mintlify Bot commented Aug 13, 2026 •

edited

Loading