MCP server - NetlyDB documentation

Enterprise Available

Enable the MCP server

builder.Services.AddNetlyDB(options =>
{
    options.Security.ApiKeyHashes = [mcpClientKeyHash]; // MCP clients send X-NetlyDB-ApiKey
});

builder.Services.AddNetlyDBMCP(
    port: 9026,
    path: "/mcp",
    maxResultLimit: 100,                          // caps rows returned by any tool
    allowedCollections: ["Products", "Articles"]); // omit to expose every collection

Transport: Streamable HTTP, stateless, at http://localhost:9026/mcp by default. There is no stdio transport.
Binding: localhost only. An agent on another machine reaches it only through a reverse proxy you configure and secure.
Authentication: required by default, shared with the REST API - an API key in X-NetlyDB-ApiKey, or JWT bearer (Enterprise). See Authentication.
TLS: with Security.EnableTls and a certificate.
Packages: your application references ModelContextProtocol and ModelContextProtocol.AspNetCore; see Packages.

An MCP client then connects with the URL and the key:

// Example client entry - the exact file and field names depend on the MCP client you use.
{
  "servers": {
    "netlydb": {
      "type": "http",
      "url": "http://localhost:9026/mcp",
      "headers": { "X-NetlyDB-ApiKey": "<your key>" }
    }
  }
}

The model does the natural-language part. The server authenticates the caller, checks the allow-list, validates the structured query against the collection's fields, and caps what comes back.

Tools

All tools are read-only. There are no insert, update or delete tools, and no MCP resources or prompts.

Tool	What it returns
`list_collections`	Names of the document and file collections the allow-list permits.
`get_collection_info`	Fields, indexes and document count of one collection.
`list_indexes`	The index names of a document collection.
`preview_documents`	The first documents of a collection (default 10, capped).
`get_document_by_id`	One document by its id.
`run_structured_query`	Documents matching structured filters, with sort and limit.
`run_structured_select`	Selected fields of the documents matching structured filters.
`run_native_query`	A NetlyDB filter string, for callers that already speak the query language.
`count_documents`	The number of documents matching a filter.
`aggregate_documents`	Count, sum, average, minimum or maximum of a field.
`full_text_search`	BM25-ranked keyword search over a full-text index.
`semantic_search`	Vector search for a text query, using the registered embedding provider.

Structured queries are JSON - filters, sort, limit and field projections - that the server validates against the collection's fields and translates into a NetlyDB query, escaping every value. The language model does the natural-language part; the server never interprets free text as a query.

Controls

allowedCollections is a case-insensitive allow-list checked by every tool. Omit it and every collection is exposed.
maxResultLimit (default 100) caps the rows any tool returns. Count and aggregate tools return no documents, but they do evaluate every matching document.
Native queries are limited to 8 KB of query text; their results are capped after execution.

What MCP does not do for you

Semantic search through MCP

semantic_search embeds the agent's text query with the IEmbeddingProvider registered in your application and runs a vector search. Without a registered provider, or without a vector index on the collection, the tool returns an error. See Semantic search.