What is NLWeb?

A practical look at NLWeb's natural-language API, MCP support, current reference implementations, and what a Lovable project still needs before it can use them.

NLWeb is an open project for adding a natural-language interface to web content. A person can ask a site a question, and an AI client can use much of the same interface through the Model Context Protocol, or MCP.

Microsoft introduced the project at Build 2025. Since then, the code and related projects have moved from the Microsoft GitHub organisation to nlweb-ai (https://github.com/nlweb-ai). The main implementation is written in Python, with a separate .NET 9 implementation (https://github.com/nlweb-ai/nlweb-net). Both are MIT-licensed.

The important qualification is that NLWeb is still developing. Its own README describes the implementation as proof-of-concept code rather than the definitive way to build an NLWeb service. The formal TypeSpec repository labels the protocol as version 0.5. This is useful technology to test, but it should not be presented as a settled web standard.

What happens when someone asks a question

The current Python reference implementation exposes /ask for its natural-language API and /mcp for MCP clients. The required input is a natural-language query. Optional values can narrow the request to a site, carry earlier conversation context, select a response mode, or turn streaming on and off.

The newer TypeSpec repository also defines Who messages for agent discovery. They are meant to help a client find which agent or tool may answer a question before it sends an Ask request. This is another reason to check the current protocol files instead of relying on the original two-endpoint summary.

The documented response modes are:

list, which returns the most relevant matching items
summarize, which adds a summary to the result list
generate, which uses retrieval-augmented generation to draft a fuller answer

Results are returned as JSON. A result can include its URL, name, source site, relevance score, generated description, and the original structured object. The project uses Schema.org vocabulary for that structured data where it fits.

The /mcp route wraps the same query capability for MCP clients. That makes it possible to expose the site's search as a tool an agent can call. It does not mean ChatGPT, Claude, or another product will automatically discover and trust every NLWeb deployment. The client still needs a supported connection and whatever authentication or approval its environment requires.

The project README also mentions future A2A support. It says "soon", so A2A belongs in the roadmap column, not the current-features column.

The reference architecture

A small local setup needs more than two routes. The official hello-world guide uses Python 3.10 or newer, an LLM provider, an embedding provider, and a local Qdrant database. You load structured content, compute embeddings, store them, and then start the web server.

For each query, the implementation can resolve conversational context, retrieve likely matches, rerank them, and optionally ask an LLM to summarize or generate an answer. The choice is configurable rather than tied to one vendor.

The current repository documents OpenAI, Anthropic, Gemini, DeepSeek, Inception, and Hugging Face for language models. Retrieval options include Qdrant, Postgres, Milvus, Snowflake, Azure AI Search, Elasticsearch, and Cloudflare AutoRAG. That flexibility is helpful, but every extra provider adds configuration, credentials, monitoring, and cost.

The repository is also clear about production work. CI/CD pipelines are not included. Its README says most production deployments will bring their own interface and connect to live databases rather than duplicate content, because copied indexes can become stale.

Schema.org helps, but NLWeb does not read your whole site by magic

The earlier version of this walkthrough made the relationship with Schema.org sound too automatic. Clean JSON-LD is useful, but the reference implementation needs an ingestion path or a live data connection.

Its database loader accepts structured JSON, tab-separated URL and JSON rows, CSV, and RSS or Atom feeds. It then computes embeddings and writes them to the configured retrieval backend. A production team may instead connect NLWeb to its live database.

This means a page with no JSON-LD is not automatically useless, and a page with excellent JSON-LD is not automatically indexed. What matters is whether the data NLWeb receives is structured, accurate, current, and suitable for the questions you want it to answer.

For a shop, that might be product name, description, price, currency, availability, and canonical URL. The visible page and the structured record should agree. Google's Rich Results Test can still help you inspect product markup, but passing that test does not prove that an NLWeb ingestion job or live connector is working. Test those separately.

Where Lovable fits

Lovable's current documentation does not advertise a built-in NLWeb integration. Its SEO and AI search review does check structured data, and published Lovable sites can provide a Markdown view to AI crawlers. Those are useful foundations, but they are different from running an NLWeb service.

For a Lovable project, I would separate the work into two parts:

Keep the site's visible content, JSON-LD, and source data accurate.
Run NLWeb as its own backend service, or connect a custom backend to the formal protocol, then expose only the data and operations that should be available.

Do not expose admin data or personal information just because MCP makes a tool callable. Add authentication where needed, rate limits, logs, and tests for stale or incorrect answers.

A sensible first test is small: load one reliable feed or product export into the local reference implementation, ask ten questions you already know the answers to, and inspect both the returned text and the underlying structured objects. That will tell you more than adding an endpoint to a production domain before the data and operating model are ready.

Sources checked

NLWeb Python reference implementation and README (https://github.com/nlweb-ai/NLWeb)
NLWeb REST API documentation (https://github.com/nlweb-ai/NLWeb/blob/main/docs/nlweb-rest-api.md)
NLWeb TypeSpec, protocol version 0.5 (https://github.com/nlweb-ai/nlweb-typespec)
Microsoft Build 2025 announcement (https://blogs.microsoft.com/blog/2025/05/19/microsoft-build-2025-the-age-of-ai-agents-and-building-the-open-agentic-web/)
Lovable SEO and AI search documentation (https://docs.lovable.dev/features/seo-aeo)