making a docs MCP server

When building our own MCP server, we knew we wanted to expose some ability to search our docs, like:

1def search_docs(query: str) -> str:

so that MCP clients like ChatGPT and Claude Code can find and read docs while working on user tasks related to Prefect.

We had seen that @mintlify had released their MCP server so we wanted to check it out, but once we plugged it into our MCP server (via FastMCP proxying), it became clear that we could not depend on it to reliably serve clients with documentation excerpts (about 1 in 3 tool calls resulted in opaque 500 failures). So despite our love for all the other things Mintlify does, we knew we needed a new docs MCP.

We could have also looked into context7 instead here

building still includes buying

so how hard could it be to just make something that looks and behaves like this?

https://docs.prefect.io/mcp

that is, one tool called SearchPrefect that takes a single query and returns excerpts with links to the actual docs pages.

well, if you have a vectorstore to use, not so hard!

turns out we do have a vectorstore via turbopuffer, since we’ve used it for our community slackbot Marvin over the last couple years.

we’ve historically ran OSS chromadb and lancedb (which are great!) and less ideal options like Pinecone/Weaviate, but turbopuffer I’ve found just seems pretty stable and surprises me the least.

so, right, making that SearchPrefect tool:

• gather, vectorize and upload docs into vectorstore
• expose a query tool as SearchPrefect in an MCP server

so that’s what we did.

the only real question left is, where do we host the MCP server?

if only we knew an easy place to host MCP servers….

ohhh yea, we do. so now that that exists:

1# uvx --with fastmcp ipython
2async with Client("https://prefect-docs.fastmcp.app/mcp") as client:
3    response = await client.call_tool(
4        "search_prefect", {"query": "how to build prefect flows"}
5    )
6    print(response)

drum roll please…

https://github.com/PrefectHQ/prefect-mcp-server/pull/48

and bada-bing bada-boom we have a docs tool on our Prefect MCP server. not the worst yak shaving exercise (we still 💙 Mintlify)