Skip to content

feat(docs,api,marketing): docs MCP server, /mcp alias, agent_auth identity types, reinstated OpenAPI spec - #5912

Merged
saddlepaddle merged 2 commits into
mainfrom
agent-readiness-round-2
Jul 24, 2026
Merged

saddlepaddle merged 2 commits into
mainfrom
agent-readiness-round-2

Conversation

@saddlepaddle

@saddlepaddle saddlepaddle commented Jul 24, 2026 •

Copy link
Copy Markdown
Collaborator

Links

Summary

  • Docs MCP server: docs.superset.sh/mcp now speaks MCP — docs_search + docs_read tools over the live fumadocs source (stateless Streamable HTTP, no auth, read-only public content). The docs page moves to /mcp-server; browser GETs get a 308 so old links keep working. This turns the scanner's "docs MCP detected but unhealthy" into a real learn-surface over the same protocol agents act with.
  • Reinstated /openapi.json (revert of the drop merged in feat(marketing,api,docs): agent-readiness surfaces — markdown twins, MCP discovery, agent auth metadata #5910): the rescan added a 5-pt "scoped permissions" check on top of the spec/schema/function-calling checks — ~16 pts total read securitySchemes and operations from an API spec. Same deliberately narrow scope: MCP transport, RFC-shaped OAuth endpoints, discovery docs; the 27 tools remain self-described via tools/list and the live server card, never hand-listed.
  • agent_auth completed with identity_types_supported: ["anonymous"] + per-type block. "Anonymous RFC 7591 registration, user claims via browser consent (PKCE)" is an accurate description of our flow, and the rescan confirmed the block is being read (register_uri was detected).
  • /mcp alias on api.superset.sh (re-export of the v2 handler, own maxDuration) and a superset.sh/mcp 307 redirect (preserves POST for MCP clients).
  • Smaller: /api/llms.txt scoped index + robots carve-out; .md twins and Accept negotiation extended to changelog pages; applicationSubCategory: "Developer Tools" in SoftwareApplication JSON-LD (nudges category classifiers away from "AI & ML").

Manual QA Checklist

  • Docs MCP: initialize, tools/list, tools/call (docs_search + docs_read) verified against local dev server; stateless per-request transport (same pattern as the api v2 route)
  • GET /mcp without Accept: text/event-stream → 308 to /mcp-server; /mcp-server page renders; nav updated (meta.json)
  • api /mcp alias returns 401 + WWW-Authenticate: Bearer resource_metadata=... unauthenticated
  • AS metadata carries the full agent_auth block (skill, register_uri, revocation_uri, identity_types_supported, anonymous.credential_types_supported)
  • /api/llms.txt serves; robots.txt allows it while still disallowing /api/
  • /changelog/<slug>.md returns text/markdown; drafts excluded
  • Production builds pass (docs verified this round; marketing + api verified in feat(marketing,api,docs): agent-readiness surfaces — markdown twins, MCP discovery, agent auth metadata #5910 and unchanged structurally)

Testing

  • bun run typecheck (marketing, api, docs — re-run on this branch after cherry-picking onto latest main)
  • bun run lint (exits 0)
  • bun run build (docs)

Design Decisions

  • OpenAPI reversal: we dropped the spec in feat(marketing,api,docs): agent-readiness surfaces — markdown twins, MCP discovery, agent auth metadata #5910 as content agents can't use. The rescan changed the math — the new scoped-permissions check plus three others only read from an API spec (~16 pts). Keeping it protocol-stable-only caps the maintenance cost: it needs updating only if the OAuth or MCP transport surface changes.
  • Docs page rename over method-splitting hacks: a route.ts owns /mcp entirely, so the page had to move; a 308 for browser GETs preserves every existing link.

Known Limitations

  • Docs MCP search is a simple term-frequency scorer over titles/descriptions/body — good enough for agent retrieval; not a search product.
  • Remaining scanner points beyond ~90 are external actions (Wikipedia/Wikidata, skills.sh npx skills add, ChatGPT directory, PyPI SDK) or a real product feature (MCP Apps ui://, ~6 pts) — documented in the plan doc.

Risks / Rollout

  • Risk: docs.superset.sh/mcp URL changes meaning (page → MCP endpoint). Mitigated by the 308 redirect for browsers; all internal links updated to /mcp-server.
  • Rollback: revert the PR — additive routes, one page rename, no data changes.

Summary by cubic

Adds a public docs MCP server, restores /openapi.json, and completes agent_auth metadata. Also adds an /mcp alias and small discoverability updates.

  • New Features

    • Docs MCP server at https://docs.superset.sh/mcp with docs_search and docs_read (Streamable HTTP, no auth). The docs page moved to /mcp-server; GET /mcp redirects (308) for browsers.
    • Reinstated https://api.superset.sh/openapi.json (OpenAPI 3.1) covering MCP transport and OAuth/discovery endpoints; tools remain self-described via tools/list.
    • agent_auth now includes identity_types_supported: ["anonymous"] with a per-type block describing anonymous DCR + PKCE consent.
    • /mcp alias on api.superset.sh to the v2 MCP handler; https://superset.sh/mcp 307-redirects to it (preserves POST).
    • GET /api/llms.txt added and allowed in robots.txt; .md twins + Accept negotiation extended to changelog pages.
    • Link headers and API catalog now point service-desc to the OpenAPI spec; docs and server-card URLs updated to /mcp-server.
    • applicationSubCategory: "Developer Tools" added to SoftwareApplication JSON‑LD.
  • Dependencies

    • Added @modelcontextprotocol/sdk to docs.

Written for commit 86eb8bf. Summary will update on new commits.

Review in cubic

Summary by CodeRabbit

  • New Features

    • Added a public OpenAPI 3.1 specification covering API, MCP, OAuth, and discovery endpoints.
    • Added a documentation MCP server with searchable and readable documentation tools.
    • Added /api/llms.txt for machine-readable developer resources.
    • Added MCP aliases, documentation links, and improved service discovery metadata.
    • Added changelog support for Markdown content and content negotiation.
  • Documentation

    • Added comprehensive MCP Server setup, authentication, tools, and client configuration guidance.
    • Documented anonymous identity support and API key authentication options.
  • Bug Fixes

    • Updated API error hints and documentation links to reference current resources.

…/mcp alias, agent_auth identity types

- docs.superset.sh/mcp now speaks MCP (docs_search + docs_read over the
  fumadocs source); the docs page moves to /mcp-server with a 308 for
  browser GETs. Fixes the 'docs MCP unhealthy' multi-surface finding
  with a real learn-surface server.
- api.superset.sh/mcp aliases the v2 MCP endpoint; superset.sh/mcp
  redirects to it (307 preserves POST for MCP clients).
- agent_auth gains identity_types_supported: [anonymous] + per-type
  block — accurately describes anonymous DCR claimed via browser consent.
- /api/llms.txt scoped index (+robots carve-out); .md twins and Accept
  negotiation extended to changelog; applicationSubCategory added.
- Reinstated /openapi.json (previous commit): the rescan hangs ~16 pts
  on it (scoped-permissions/schema/function-calling read the spec).

Claude-Session: https://claude.ai/code/session_01GbjRvApZBmhsSkfHzihp6x
@coderabbitai

coderabbitai Bot commented Jul 24, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

The changes expand Superset’s agent-readiness surfaces with MCP documentation and aliases, an OpenAPI specification, anonymous authentication metadata, updated discovery descriptors, agent-readable markdown resources, changelog markdown routing, and related documentation.

Changes

API protocol and discovery

Layer / File(s) Summary
API protocol and discovery contracts
apps/api/src/app/openapi.json/route.ts, apps/api/src/app/mcp/route.ts, apps/api/src/app/.well-known/*, apps/api/src/app/api/*, apps/api/src/lib/agent-auth-metadata.ts
Adds the OpenAPI 3.1 endpoint, /mcp alias, MCP discovery entries, anonymous auth metadata, and updated API error hints.

Documentation MCP server

Layer / File(s) Summary
Documentation MCP server
apps/docs/src/app/mcp/route.ts, apps/docs/content/docs/mcp-server.mdx, apps/docs/content/docs/meta.json, apps/docs/package.json
Adds the superset-docs MCP server with search/read tools, streamable HTTP handling, legacy redirects, client setup instructions, authentication guidance, and tool documentation.

Marketing discovery and resource surfaces

Layer / File(s) Summary
Marketing discovery and resource surfaces
apps/marketing/next.config.ts, apps/marketing/src/app/.well-known/*, apps/marketing/src/app/agents.md/route.ts, apps/marketing/src/app/api/llms.txt/route.ts, apps/marketing/src/lib/llms.ts, apps/marketing/src/app/robots.txt/route.ts, apps/marketing/src/components/JsonLd/JsonLd.tsx
Updates MCP and OpenAPI discovery links, adds agent-readable resources, permits crawling of /api/llms.txt, and classifies the application as Developer Tools.

Markdown content surfaces

Layer / File(s) Summary
Markdown content surfaces
apps/marketing/src/app/md/[...path]/route.ts, apps/marketing/src/proxy.ts, plans/done/20260722-agent-readiness.md
Adds changelog markdown loading and content negotiation, and records the expanded agent-readiness implementation plan.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant MCPClient
  participant SupersetAPI
  participant DocsMCP
  participant DiscoveryMetadata
  MCPClient->>DiscoveryMetadata: Read MCP and OpenAPI descriptors
  DiscoveryMetadata-->>MCPClient: MCP endpoint and API specification URLs
  MCPClient->>SupersetAPI: Use API or MCP endpoint
  MCPClient->>DocsMCP: Search or read documentation
  DocsMCP-->>MCPClient: Documentation results or markdown
Loading

Possibly related PRs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 6.25% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title uses conventional commit style and clearly summarizes the main changes across docs, API, and marketing.
Description check ✅ Passed The description covers what changed, why, testing, checklist items, risks, and rollout details, so it is mostly complete.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch agent-readiness-round-2

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@github-actions

github-actions Bot commented Jul 24, 2026 •

Copy link
Copy Markdown
Contributor

🧹 Preview Cleanup Complete

The following preview resources have been cleaned up:

  • ✅ Neon database branch

Thank you for your contribution! 🎉

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (2)
apps/api/src/app/openapi.json/route.ts (1)

1-3: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Hardcoded production origin instead of request-derived origin.

API_URL/MARKETING_URL/DOCS_URL are literal https://... strings baked into the spec (servers: [{ url: API_URL }], contact/terms links, etc.), unlike the sibling discovery routes added in this same PR (e.g. .well-known/mcp/route.ts, .well-known/mcp/server-card.json/route.ts) which derive the origin via getRequestOrigin(request). On any non-production origin (preview/staging deployment), this spec will still advertise the production API as the servers entry, so agents/tools consuming /openapi.json there would be pointed at the wrong host.

♻️ Suggested direction
-const API_URL = "https://api.superset.sh";
-const MARKETING_URL = "https://superset.sh";
-const DOCS_URL = "https://docs.superset.sh";
+import { getRequestOrigin } from "`@/lib/oauth-metadata`";
+// derive API_URL from request origin inside GET(), keep MARKETING_URL/DOCS_URL as constants if they never vary by environment

Also applies to: 90-91, 116-116, 592-599

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/api/src/app/openapi.json/route.ts` around lines 1 - 3, Update the
OpenAPI route handler to derive the request origin with the existing
getRequestOrigin(request) helper instead of using hardcoded API_URL,
MARKETING_URL, and DOCS_URL values. Build the servers, contact, terms, and
related links from that request-derived origin so preview and staging
specifications advertise their own host; remove or replace the affected
constants while preserving the existing OpenAPI structure.
apps/docs/src/app/mcp/route.ts (1)

92-97: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Add CORS handling to the MCP transport endpoint.

handleMcp() returns transport.handleRequest(request) directly, and the route only changes GET for human redirects. WebStandardStreamableHTTPServerTransport does not add CORS headers automatically, so anonymous browser-based MCP clients calling docs.superset.sh/mcp can be blocked by same-origin policy. Wrap the transport responses with the required Access-Control-Allow-* headers and handle the OPTIONS preflight explicitly.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/docs/src/app/mcp/route.ts` around lines 92 - 97, Update handleMcp to
explicitly respond to OPTIONS preflight requests and add the required
Access-Control-Allow-* headers to transport responses, including responses
returned by transport.handleRequest(request). Preserve the existing MCP server
connection and request handling behavior for non-preflight requests.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/marketing/next.config.ts`:
- Around line 59-63: Update the `/mcp` redirect configuration in the Next.js
redirects list to set `permanent` to true, producing the required permanent 308
redirect while preserving the existing source and destination.

---

Nitpick comments:
In `@apps/api/src/app/openapi.json/route.ts`:
- Around line 1-3: Update the OpenAPI route handler to derive the request origin
with the existing getRequestOrigin(request) helper instead of using hardcoded
API_URL, MARKETING_URL, and DOCS_URL values. Build the servers, contact, terms,
and related links from that request-derived origin so preview and staging
specifications advertise their own host; remove or replace the affected
constants while preserving the existing OpenAPI structure.

In `@apps/docs/src/app/mcp/route.ts`:
- Around line 92-97: Update handleMcp to explicitly respond to OPTIONS preflight
requests and add the required Access-Control-Allow-* headers to transport
responses, including responses returned by transport.handleRequest(request).
Preserve the existing MCP server connection and request handling behavior for
non-preflight requests.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d9fa0af1-28ba-4a22-8b47-b4a74bfca9c3

📥 Commits

Reviewing files that changed from the base of the PR and between ae7779d and 86eb8bf.

⛔ Files ignored due to path filters (1)
  • bun.lock is excluded by !**/*.lock
📒 Files selected for processing (24)
  • apps/api/src/app/.well-known/mcp/route.ts
  • apps/api/src/app/.well-known/mcp/server-card.json/route.ts
  • apps/api/src/app/api/[...unmatched]/route.ts
  • apps/api/src/app/api/route.ts
  • apps/api/src/app/mcp/route.ts
  • apps/api/src/app/openapi.json/route.ts
  • apps/api/src/lib/agent-auth-metadata.ts
  • apps/docs/content/docs/mcp-server.mdx
  • apps/docs/content/docs/meta.json
  • apps/docs/package.json
  • apps/docs/src/app/mcp/route.ts
  • apps/marketing/next.config.ts
  • apps/marketing/src/app/.well-known/agent-card.json/route.ts
  • apps/marketing/src/app/.well-known/api-catalog/route.ts
  • apps/marketing/src/app/.well-known/mcp/route.ts
  • apps/marketing/src/app/.well-known/mcp/server-card.json/route.ts
  • apps/marketing/src/app/agents.md/route.ts
  • apps/marketing/src/app/api/llms.txt/route.ts
  • apps/marketing/src/app/md/[...path]/route.ts
  • apps/marketing/src/app/robots.txt/route.ts
  • apps/marketing/src/components/JsonLd/JsonLd.tsx
  • apps/marketing/src/lib/llms.ts
  • apps/marketing/src/proxy.ts
  • plans/done/20260722-agent-readiness.md

Comment on lines +59 to +63
{
source: "/mcp",
destination: "https://api.superset.sh/mcp",
permanent: false,
},

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

BASE_URL="${BASE_URL:-https://superset.sh}"
curl -sS -D - "$BASE_URL/mcp" -o /dev/null | sed -n '1p;/^[Ll]ocation:/p'
# Expect an HTTP 308 response.

Repository: superset-sh/superset

Length of output: 175


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== next config excerpt =="
if [ -f apps/marketing/next.config.ts ]; then
  nl -ba apps/marketing/next.config.ts | sed -n '1,120p'
else
  echo "apps/marketing/next.config.ts not found"
  fd -a 'next\.config\.(ts|js|mjs|cjs)' . | sed -n '1,20p'
fi

echo
echo "== mcp redirect mentions =="
rg -n '"source":\s*"/mcp"|source:\s*["'\'']\s*/mcp\s*["'\'']|permanent:\s*(true|false)' apps/marketing/next.config.ts apps 2>/dev/null || true

echo
echo "== repo diff/stat summary =="
git diff --stat || true
git diff -- apps/marketing/next.config.ts | sed -n '1,160p' || true

Repository: superset-sh/superset

Length of output: 224


🌐 Web query:

Next.js redirects permanent false true 307 308 next.config.js documentation

💡 Result:

In Next.js, the redirects configuration in next.config.js uses the permanent property to determine the HTTP status code for a redirect [1][2]. When you define a redirect, you set the permanent property to either true or false: - permanent: true: Uses a 308 status code. This informs clients and search engines that the redirect is permanent and should be cached [1][3]. - permanent: false: Uses a 307 status code. This indicates a temporary redirect, which is not cached by clients [1][4]. Next.js uses 307 and 308 status codes specifically to preserve the original HTTP request method [1][3]. Traditionally, 301 (permanent) and 302 (temporary) status codes were used, but these often caused browsers to change the request method to GET regardless of the original method (e.g., turning a POST into a GET). By using 307 and 308, Next.js ensures the original request method is maintained [1][4]. In rare cases where you need a different status code for legacy HTTP client compatibility, you can use the statusCode property instead of permanent, but you cannot use both simultaneously [1][3]. Additionally, when permanent: true is used, Next.js automatically adds a Refresh header to ensure IE11 compatibility [3][4].

Citations:


🌐 Web query:

Next.js permanent redirect 308 Next.js redirects next.config.js permanent

💡 Result:

In Next.js, a permanent redirect is configured in your next.config.js file using the redirects function [1][2]. By setting the permanent property to true within a redirect object, Next.js will automatically use the 308 HTTP status code [1][2][3]. Configuration Example: module.exports = { async redirects { return [ { source: '/old-path', destination: '/new-path', permanent: true, // Triggers a 308 status code }, ]; }, }; Key Details: - 308 Status Code: Next.js uses 308 for permanent redirects and 307 for temporary redirects [1][2]. These status codes are preferred over the older 301/302 because they explicitly preserve the request method (e.g., ensuring a POST request remains a POST request after the redirect) [1][2][4]. - Caching: Setting permanent: true instructs browsers and search engines to cache the redirect permanently [1][2]. - Alternative Methods: For redirects based on logic within your application (rather than path matching), you can use the permanentRedirect function in Server Components, Route Handlers, or Server Actions, which also defaults to a 308 status code [5][6]. - Custom Status Codes: If you require a different status code (such as for compatibility with older clients), you can use the statusCode property instead of the permanent property, though you cannot use both at the same time [1][2][3].

Citations:


🌐 Web query:

Superset official mcp URL 308 permanent

💡 Result:

There is no single "official MCP URL" for Apache Superset; instead, the MCP service URL is determined by your specific deployment configuration [1][2]. For most production environments, the MCP service is accessed via your main Superset base URL with an added /mcp suffix (e.g., https://your-superset-instance.com/mcp) [1][3][4]. In development environments, it is typically available at http://localhost:5008 [3][2]. Regarding 308 Permanent Redirects: 1. URL Handling: If you are encountering a 308 error when accessing Superset endpoints, it is often due to missing trailing slashes in the URL requested by the client [5][6]. Flask, which powers Superset, may issue a 308 redirect to append the slash to match the defined route [5]. 2. Proxy Configuration: A 308 error can also occur if your reverse proxy (e.g., Nginx, Apache) is misconfigured or if there is a mismatch between your environment's base URL settings and the actual traffic routing [1][7][6]. 3. Troubleshooting: - Ensure your Superset configuration (superset_config.py) explicitly sets WEBDRIVER_BASEURL_USER_FRIENDLY to the correct public-facing URL of your instance [1][3]. - If behind a proxy, verify that your ingress or proxy rules correctly route /mcp/* traffic to the MCP service port (default 5008) without improper redirects [8][7]. - For AI clients (like Claude Desktop or ChatGPT), ensure you are providing the full, correct URL including the /mcp path as configured by your administrator [9][4]. For definitive setup instructions for your specific instance, consult your organization's internal documentation or the official Apache Superset MCP administration guide [2][4].

Citations:


Make the /mcp redirect permanent.

permanent: false maps to a temporary 307 redirect in Next.js. permanent: true preserves the request method while using the 308 status expected for a stable legacy URL.

Proposed fix
 				source: "/mcp",
 				destination: "https://api.superset.sh/mcp",
-				permanent: false,
+				permanent: true,
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
{
source: "/mcp",
destination: "https://api.superset.sh/mcp",
permanent: false,
},
{
source: "/mcp",
destination: "https://api.superset.sh/mcp",
permanent: true,
},
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/marketing/next.config.ts` around lines 59 - 63, Update the `/mcp`
redirect configuration in the Next.js redirects list to set `permanent` to true,
producing the required permanent 308 redirect while preserving the existing
source and destination.

This branch was previously deployed

1 inactive deployment
preview — 86eb8bf4 Deployed Jul 24, 2026 by saddlepaddle via Deploy Web #6814
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant