Skip to content

Server card omits submit_feedback: advertised tool list is missing a tool the endpoint serves (50/51 sites checked) #7313

Open

Description

@he110

The docs for server card endpoints say:

Each server card includes the standard discovery fields and a tools array that describes the MCP tools the server advertises. Use this to pre-populate tool metadata in MCP clients without making an initialize call to the server.

A client that does that gets an incomplete tool list. On your own docs site:

curl -s https://www.mintlify.com/docs/.well-known/mcp/server-card.json | jq -c '[.tools[].name]'
# ["search_mintlify","query_docs_filesystem_mintlify"]

curl -s -X POST https://www.mintlify.com/docs/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
| sed -n 's/^data: //p' | jq -c '[.result.tools[].name]'
# ["search_mintlify","query_docs_filesystem_mintlify","submit_feedback"]

submit_feedback is served but not advertised. /ai/model-context-protocol#mcp-tools documents it as one of the three tools, so the docs and the endpoint agree with each other — the card is the odd one out.

Not just your site. I run a registry that reads tools/list from public keyless MCP endpoints on a schedule; 51 of the 79 it tracks are hosted Mintlify sites. I checked the card against the live tool list on all 51 today (2026-09-09):

  • 50/51 serve /.well-known/mcp/server-card.json (one 404s)
  • 49 of those 50 advertise exactly 2 tools; one advertises 0
  • 0 of 50 advertise submit_feedback
  • 51/51 live endpoints serve it

I seeded that server list myself, so 51 is my sample, not a census of your customers.

The changelog looks like it explains the ordering — server cards shipped May 29, 2026, and the submit_feedback tool shipped July 2, 2026, so the card generator may simply predate the third tool.

Two things that might need fixing, and I can't tell from outside which:

  1. The card generator, if it should be emitting all three tools.
  2. The sentence recommending the card as a substitute for initialize, if the card is intentionally a subset — right now it reads as authoritative.

Reproduce fleet-wide:

curl -s https://he110.github.io/mcp-drift-registry/api/registry.json \
| jq -c '[.servers[] | select([.tools[].name]|any(startswith("query_docs_filesystem_")))
      | [.tools[].name]|any(.=="submit_feedback")]
      | {tenants:length, serving_submit_feedback:(map(select(.))|length)}'
# {"tenants":51,"serving_submit_feedback":51}

Built with an AI coding agent; the measurement is deterministic — fetch, canonicalise, diff — no model in the pipeline.

Activity

  1. he110 commented on Sep 9, 2026

    @he110
    Author

    Follow-up: the same card on your own documentation site disagrees with its endpoint in three more places, and one cause seems to explain all four.

    curl -s https://mintlify.com/docs/.well-known/mcp/server-card.json
    
    curl -s -X POST https://mintlify.com/docs/mcp \
      -H 'content-type: application/json' \
      -H 'accept: application/json, text/event-stream' \
      -H 'mcp-protocol-version: 2025-06-18' \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
    
    server card tools/list
    tools search_mintlify, query_docs_filesystem_mintlify those two plus submit_feedback
    properties.query.description "A query to search the content with." "Search query"
    additionalProperties absent false
    url https://mintlify.subdirectory-docs.mintlify.me/docs/mcp served from https://www.mintlify.com/docs/mcp

    The url row looks like the one worth prioritising. ai/model-context-protocol.mdx says to use the card "to pre-populate tool metadata in MCP clients without making an initialize call to the server", and the example card on that page carries "url": "https://your-docs.com/mcp" and "description": "Search query" — both of which match the live endpoint rather than the card actually served. It is not confined to this one site: as of the 2026-09-09T16:03Z snapshot linked below, of the 48 endpoints where there is a tool list to compare, 44 name a Mintlify-owned build host in url — 43 under *.mintlify.me, one under *.mintlify.dev — rather than the site's own domain. Four name their own.

    Reading: the card is generated in the build environment while the MCP runtime ships separately, so the card trails it. That would account for the missing tool (your changelog dates server cards to 29 May and submit_feedback to 2 July), the older parameter description, the absent additionalProperties and the internal hostname all at once — one lag rather than four bugs.

    Two things I checked that did not hold up, in case they save you time. Unknown arguments are accepted on every endpoint I tried despite additionalProperties: false being served, so nothing appears to be breaking for clients today. And one site serves a card with an empty tools array while the endpoint serves three; I have no evidence for why, so I am not claiming a mechanism.

    Data and method: https://he110.github.io/mcp-drift-registry/api/advertised.json

  2. ethanpalm commented on Sep 9, 2026

    @ethanpalm
    Collaborator

    Hi @he110, thanks for creating this issue and your detailed reporting. I'm triaging this for our team to resolve internally. Appreciate you taking the time to help improve Mintlify 😄

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions