Skip to main content
Glama
genckastrati

nectr-mcp

by genckastrati
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

nectr-mcp

An MCP server for nectr, the markdown library for your LLMs.

It lets a model search your library, read any saved page as clean markdown, save new pages, and list your projects. You don't need to paste links into the chat.

  • Search: a model can't guess your permalinks, but it can call search_library("pricing page").

  • Private pages: pages you haven't shared have no working public link, but your key can still read them.

  • Saving: "save these docs and keep them current" becomes one step, and nectr re-crawls them on your plan's schedule.

  • Freshness: every read says when the page was last fetched.

Setup

  1. In nectr, open Settings → API keys and create a key. It starts with nct_.

  2. Add the server to your MCP client's configuration. Most desktop and editor clients use an mcpServers block like this:

{
  "mcpServers": {
    "nectr": {
      "command": "npx",
      "args": ["-y", "nectr-mcp"],
      "env": {
        "NECTR_API_KEY": "nct_your_key_here"
      }
    }
  }
}

  1. Restart the client. The four tools below should appear.

Node.js 20 or newer is required.

Variable

Required

Default

Purpose

NECTR_API_KEY

yes

—

Your nct_ API key

NECTR_URL

no

https://nectr.ch

The nectr site to talk to, for a self-hosted instance

Related MCP server: data-olympus MCP server

Tools

Tool

What it does

Writes?

search_library(query?, limit?)

Finds saved pages by title or URL. Returns ids, URLs, freshness and a two-sentence summary per page, but not the bodies. Leave out query to list the most recently refreshed pages.

no

get_page(id | url, max_chars?)

Returns the clean markdown of one page, with when it was last fetched. Long pages are cut off at 40,000 characters by default; ask for more with max_chars.

no

convert_url(url, project_id?, force_refresh?)

Saves a web page, PDF or DOCX to your library, optionally filed under a project. Counts against your monthly conversion quota unless the page is already saved.

yes

list_projects()

Lists your projects with page counts and each project's public llms.txt URL.

no

There is deliberately no delete. A model that could delete your library by misreading a request isn't worth the convenience.

Search returns summaries rather than bodies so that looking around your library doesn't fill the model's context. It reads a full page only when it chooses to.

Limits and errors

The server uses the same developer API as any other script, so your plan's limits apply unchanged. Errors are worded so a model knows whether to retry:

nectr says

The model is told

401: the key is invalid or revoked

Don't retry; you need a new key

402: over the monthly quota

Don't retry until the quota resets

422: the page can't be read (for example, it's behind a login)

nectr's reason, as given

429: rate limited

How many seconds to wait

503: the converter is busy

Retry in a few seconds

Security

Your API key is stored in plain text in your MCP client's config file. That's normal for MCP servers, but anyone who can read that file can use the key.

  • Create a dedicated key for each client, so you can revoke one without breaking the others.

  • If a key leaks, delete it under Settings → API keys in nectr. It stops working immediately.

  • This server only ever reads and adds pages. The key itself is broader: it has the same access to the nectr API as your account, deletion included, so treat it like a password.

Development

npm install
npm run typecheck
npm test
npm run build
NECTR_API_KEY=nct_... node dist/index.js   # speaks MCP over stdio

The tests run against a fake nectr API (test/fake-api.ts) and through a real MCP client over an in-memory transport (test/server.test.ts).

License

MIT

Available Tools

4 tools
convert_urlSave a page to nectrA
Idempotent

Convert a web page, PDF or DOCX to clean markdown and save it to the user's nectr library, where it is re-crawled automatically to stay current. Returns the new page's id and summary. Counts against the user's monthly conversion quota unless the page is already saved.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesThe http(s) URL to save.
project_idNoOptional project id (from list_projects) to file it under.
force_refreshNoRe-crawl now even if the page is already saved (counts against the quota).

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds real behavioral context beyond annotations: automatic re-crawling to stay current, monthly quota consumption, and the exception when already saved. Complements openWorldHint and idempotentHint. Could have noted auth or what happens on quota exhaustion.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly packed sentences, front-loaded with the core action, followed by return value and quota caveat. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, side effects (re-crawl, quota), and return values, which is strong for a no-output-schema tool. Missing explicit auth/permission requirements and error behavior, but nothing critical for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all three parameters are already documented in the schema. The description only alludes to the 'already saved' condition (relevant to force_refresh) without adding syntax or format detail. Baseline 3 when schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource chain: converts a web page/PDF/DOCX to markdown and saves it to the nectr library. Distinguishes itself from siblings (search_library, get_page, list_projects) by being the only write/conversion tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage (when you want to save a page), but never explicitly routes to alternatives or states when NOT to use it. Siblings like get_page (read an existing page) aren't contrasted. The quota caveat hints at a cost consideration but not a decision rule.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_pageRead a saved pageA
Read-only

Get the clean markdown of one saved nectr page, by id (from search_library) or by its original URL. Includes when it was last fetched. Works for private pages too.

ParametersJSON Schema
NameRequiredDescriptionDefault
idNoPage id from search_library or convert_url.
urlNoThe page's original URL, if the id is not known.
max_charsNoTruncate the body after this many characters (default 40000).

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false). The description adds real behavioral value beyond them: that private pages are also retrievable, and that the response includes the last-fetched timestamp. It omits details like rate limits or truncation behavior (though max_chars partly covers that in the schema).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with the resource and the retrieval modes front-loaded; every clause carries information and nothing is redundant with the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully sketches the return payload (markdown body plus last-fetched time) and notes private-page support. Coverage is good for a simple read tool, though it could mention whether missing/unfetched pages error or return empty.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters are already documented, including the default truncation limit and the id provenance. The description restates the id/url sourcing rather than adding syntax or edge-case detail, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Get the clean markdown of one saved nectr page') and clarifies the two addressing modes (id or original URL). It also implicitly distinguishes itself from search_library and convert_url by naming them as id sources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for how to obtain the identifiers ('id from search_library or convert_url', 'URL if the id is not known'), which tells the agent when this tool is applicable. It stops short of explicit exclusions or stating when to prefer one identifier over the other beyond the fallback hint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_projectsList nectr projectsA
Read-only

List the user's nectr projects with their page counts and public llms.txt URLs.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare it as a safe read (readOnlyHint=true, openWorldHint=false), so the safety burden is covered. The description goes beyond that by disclosing the payload contents – page counts and public llms.txt URLs – which is useful behavioral context absent from the annotations. It omits ordering, pagination, and scope (all projects vs. shared), keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with a precise verb, resource, and return payload. No filler and nothing restated from the name or title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no parameters, the description must at least say what comes back, and it does (page counts and llms.txt URLs). Annotations cover the safety profile. Minor gaps remain around ordering/pagination and whether the listing is exhaustive, but nothing blocks correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4; there is no parameter semantics to explain. The description correctly makes no attempt to describe nonexistent inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (List) and resource (the user's nectr projects) and even names what each entry contains (page counts, llms.txt URLs). It does not explicitly differentiate from siblings, though search_library/get_page/convert_url are clearly distinct, so no real ambiguity exists.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the word 'List' and the scope 'the user's projects' – an agent can infer this is the discovery/enumeration entry point. There is no explicit when-to-use, when-not-to-use, or named alternative, and no prerequisite (e.g., authentication) is stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_librarySearch the nectr libraryA
Read-only

Search the user's saved nectr pages by title or URL. Returns ids, URLs, freshness and a short summary per page, not the page bodies. Omit query to list the most recently refreshed pages.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax results (default 10).
queryNoWords from the title or URL. Omit to list recent pages.

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful disclosure beyond that: exactly which fields come back (ids, URLs, freshness, short summary) and, importantly, that page bodies are NOT returned, which steers agents to get_page for content.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the verb and resource, then the return shape, then the default behavior. No filler and no repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-shape burden and does so adequately, including the negative case (no bodies). It omits pagination/result-count behavior and any note on empty results, which are minor gaps for a 2-param read tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented with defaults, bounds and the omit-to-list behavior. The description restates the omit-query semantics but adds no new syntax or format detail, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource plus scope: 'Search the user's saved nectr pages by title or URL.' That clearly separates it from siblings like convert_url or list_projects, though it never names an alternative tool or explains how it differs from get_page when a page id is already known.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete context for the parameterless case ('Omit query to list the most recently refreshed pages'), which is real when-to-use guidance. It stops short of an explicit when-not-to-use or a named alternative, so it does not reach 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observedconvert_url
    • First observedget_page
    • First observedlist_projects
    • First observedsearch_library
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct role: search_library finds pages by metadata, get_page retrieves a page's body, convert_url adds/saves new content, and list_projects enumerates projects. The search-vs-get boundary is well explained (metadata vs. full markdown), so misselection is unlikely.

Naming Consistency5/5

All four names follow a strict verb_noun snake_case pattern (search_library, get_page, convert_url, list_projects). No mixing of conventions or vague verbs.

Tool Count4/5

Four tools is a tight, well-scoped set that maps cleanly to the core read/add/project workflows. It leans slightly thin for a library service, but each tool earns its place.

Completeness3/5

The read and create paths are covered (search, get, convert), but there is no delete/update for saved pages and projects can only be listed, not created or managed. These are notable lifecycle gaps an agent would hit.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers