Documentation

How to connect an agent to Nodiom Cloud, authenticate, and address structure inside a Markdown document.

Quickstart

Nodiom Cloud speaks the Model Context Protocol over HTTP at https://api.nodiom.md/mcp. Any MCP client can connect to it; two common ones:

Claude Code

claude mcp add --transport http nodiom-cloud https://api.nodiom.md/mcp \
  --header "Authorization: Bearer $NODIOM_API_KEY"

Your own agent (Node.js, MCP SDK)

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(
  new URL('https://api.nodiom.md/mcp'),
  { requestInit: { headers: { Authorization: `Bearer ${process.env.NODIOM_API_KEY}` } } },
);

const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(transport);

const result = await client.callTool({
  name: 'nodiom_append',
  arguments: {
    doc_id: 'project-wiki',
    selector: '## Tasks',
    new_content: '- [ ] Ship the docs page',
  },
});

console.log(result.content[0].text);

Authentication

Every request needs an API key in the Authorization header:

Authorization: Bearer nk_live_...

Create a key from Dashboard → API Keys. The raw key is shown once, at creation — store it somewhere safe, since Nodiom Cloud only ever keeps a hash of it. Revoking a key takes effect immediately.

Selectors

A selector addresses a location inside a document's Markdown structure — the same syntax used by the open-source nodiom library. It's a " > "-separated path, each segment matching one node.

Heading segments

"# Project Alpha"              → the H1 "Project Alpha" and everything under it
"## Tasks"                     → any top-level H2 named "Tasks"
"# Project Alpha > ## Tasks"   → the H2 "Tasks" nested under H1 "Project Alpha"

The number of #characters must match the heading's actual depth in the document.

Element segments

"## Tasks > li[0]"   → first list item under ## Tasks
"## Tasks > li[-1]"  → last list item (negative indexing)
"## Notes > p[0]"    → first paragraph under ## Notes

Valid element types: p, li, code, blockquote, table, hr.

"Content under ## Tasks" means everything after that heading until the next heading of equal or lesser depth — the same way you'd read it.

Tool reference

11 tools, grouped by what they do. doc_id identifies a document within your account (see nodiom_list_docs); a fresh account starts with none — create one with nodiom_create_doc.

Document management

nodiom_list_docs(none)

Lists every document ID in your account, with last-updated time.

nodiom_create_docdoc_id, content

Creates a new document. Does nothing if the ID already exists.

nodiom_get_docdoc_id

Returns the full Markdown content of a document.

nodiom_delete_docdoc_id

Permanently deletes a document.

Reading structure

nodiom_treedoc_id

Returns a document's structural outline as nested JSON. Use this first to see what's in a document.

nodiom_readdoc_id, selector

Returns the Markdown at a selector.

nodiom_read_listdoc_id, selector

Returns the list items under a selector as a JSON array of strings.

nodiom_querydoc_id, selector

Returns metadata about a selector: exists, type, depth, childCount.

Writing structure

nodiom_writedoc_id, selector, new_content

Replaces the content at a selector. The heading itself is preserved.

nodiom_appenddoc_id, selector, new_content

Appends content after the last item in a section.

nodiom_deletedoc_id, selector

Removes the node or section matched by a selector.

Write operations save automatically — there's no separate save/commit step.

Operations & billing

Every successful tool call above counts as one operation against your plan's monthly quota. Failed calls — a bad selector, a missing document — aren't counted. See pricing for plan details, or manage billing if you're signed in.

Questions not covered here? dev@synexiomlabs.com.