Perdhevi's Thought

Most MCP tutorials start with installing the SDK. You register a tool, connect a client, and the model calls your function. It works, and it feels like magic.

It isn’t magic. Underneath is a short JSON-RPC conversation over one HTTP endpoint. I wrote that conversation by hand before I touched the SDK, and it changed how I read everything that came after.

The project is obsidian-mcp, a local MCP server that lets AI clients search and read my Obsidian vault and save new notes into an inbox folder. I built it to learn how MCP, embeddings and vector search fit together, and I built it to be tutorial material: a ten-step guide where every step ends with something that runs. A tutorial that starts at the SDK teaches the SDK. I wanted step one to show the protocol itself.

The code is at github.com/perdhevi/obsidian-mcp, and the step-by-step walkthrough is in the build guide. This post is the why, and what each step taught me. The guide is the how.

The rules of the conversation

Every MCP message is JSON-RPC 2.0. There are only two shapes to know:

• A request has an id and expects a reply with the same id.
• A notification has no id and gets no reply.

Over the Streamable HTTP transport, the client POSTs every message to one URL, /mcp in my case. A request gets back JSON (or an SSE stream, which my raw version doesn’t do). A notification gets HTTP 202 Accepted with an empty body.

A session goes in three moves: the client sends initialize, then a notifications/initialized notification, then real work.

The raw server

Step 1 is a single file, src/raw-server.js, using only node:http. No dependencies. This is the guide’s version of the dispatcher:

js

function handle({ id, method, params }) {
  switch (method) {
    case "initialize":
      return { result: {
        protocolVersion: params.protocolVersion,
        capabilities: { tools: {} },
        serverInfo: { name: "vault-raw", version: "0.0.1" },
      }};
    case "tools/list":
      return { result: { tools: TOOLS } };
    case "tools/call":
      if (params.name === "ping")
        return { result: { content: [{ type: "text", text: "pong" }] } };
      return { result: { isError: true, content: [{ type: "text", text: `Unknown tool ${params.name}` }] } };
    default:
      return { error: { code: -32601, message: "Method not found" } };
  }
}

And the HTTP side, which is where notifications and broken input are handled:

js

http.createServer((req, res) => {
  if (req.url !== "/mcp" || req.method !== "POST") return res.writeHead(405).end();
  let body = "";
  req.on("data", (c) => (body += c));
  req.on("end", () => {
    let msg;
    try { msg = JSON.parse(body); }
    catch { return res.writeHead(400).end(JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } })); }
    if (msg.id === undefined) return res.writeHead(202).end(); // notification
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ jsonrpc: "2.0", id: msg.id, ...handle(msg) }));
  });
}).listen(3000, "127.0.0.1", () => console.error("raw MCP on :3000"));

That’s under 50 lines, and from the server’s side it’s most of MCP.

What’s on the wire

Here’s the whole conversation, driven by hand with curl. The responses below are what the repo’s raw-server.js returns. That file has an echo tool on top of the guide’s ping, which is one of the guide’s exercises.

bash

mcp() {
  curl -s http://127.0.0.1:3000/mcp -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/event-stream' -d "$1"; echo
}

1. initialize

→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"sh","version":"1"}}}
← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"vault-raw","version":"0.0.1"}}}

This is the handshake. The client says which protocol version it speaks and what it supports. The server answers with a version, its capabilities (here, only tools) and its name.

My raw server just echoes back whatever protocolVersion the client sent. That’s enough to get a client talking, and it’s also a shortcut a real server shouldn’t take. A real server answers with a version it actually supports.

2. notifications/initialized

→ {"jsonrpc":"2.0","method":"notifications/initialized"}
← HTTP 202, empty body

No id, so no reply. In the raw server that’s one line: no id, return 202, stop. When you test from a shell you check the status code, because there’s nothing else to look at.

3. tools/list

→ {"jsonrpc":"2.0","id":2,"method":"tools/list"}
← {"jsonrpc":"2.0","id":2,"result":{"tools":[
     {"name":"ping","description":"Health check. Returns pong.","inputSchema":{"type":"object","properties":{}}},
     {"name":"echo","description":"Echoes the input.","inputSchema":{"type":"object","properties":{"text":{"type":"string","description":"The text to echo."}}}}]}}

Each tool is a name, a description and a JSON Schema for its input. That’s everything the model gets when it decides whether to call your tool. Seeing it raw made it obvious that the description is part of the interface, not documentation.

4. tools/call

→ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ping","arguments":{}}}
← {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"pong"}]}}

The result is a list of content blocks, usually text.

5. Two kinds of errors

This is the part worth slowing down for.

→ {"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"nope","arguments":{}}}
← {"jsonrpc":"2.0","id":4,"result":{"isError":true,"content":[{"type":"text","text":"Unknown tool nope"}]}}

→ {"jsonrpc":"2.0","id":5,"method":"resources/list"}
← {"jsonrpc":"2.0","id":5,"error":{"code":-32601,"message":"Method not found"}}

→ {"jsonrpc":
← HTTP 400 {"jsonrpc":"2.0","id":null,"error":{"code":-32700,"message":"Parse error"}}

Calling a tool that doesn’t exist is not a protocol error. It’s a normal, successful response with isError: true in the result. That goes back to the model, which can read the message and try something else.

An unknown method or a broken body is different. Those come back as JSON-RPC error objects, and they’re for the client, not the model. The guide puts it in one line: the model sees tool errors; protocol errors are for the client.

That distinction shapes how you write every tool afterwards. When a tool fails, you return a message the model can act on, and the server keeps going.

What the SDK takes off your hands

Step 2 replaces the raw server with the official SDK on Express, using the Streamable HTTP transport in stateless mode, with a fresh server instance per request:

js

app.post("/mcp", async (req, res) => {
    const server = buildServer();
    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
    res.on("close", () => { transport.close(); server.close(); });
    await server.connect(transport);
    await transport.handleRequest(req, res, req.body);
});

The first real tool is get_note:

js

server.registerTool("get_note", {
    description: "Read one Obsidian note by its vault-relative path, e.g. 'Projects/Idea.md'.",
    inputSchema: { path: z.string().describe("Vault-relative path ending in .md") },
    annotations: { readOnlyHint: true },
}, async ({ path }) => {
    try {
        const n = await readNote(path);
        return text(`# ${n.path}\n\nFrontmatter: ${JSON.stringify(n.frontmatter)}\n\n${n.content}`);
    } catch (e) {
        return fail(`Could not read ${path}: ${e.message}`);
    }
});

Because I’d written the dispatcher myself, I could map every part of this back to the wire:

• registerTool is an entry in the tools/list response plus a branch in tools/call.
• The zod inputSchema becomes the JSON Schema the client sees, and incoming arguments are validated against it.
• fail is a two-line helper that adds isError: true, the same result shape as the unknown-tool case above.
• annotations.readOnlyHint is extra metadata in the tool list that tells clients this tool changes nothing.

The raw version deliberately skipped things the SDK handles: session IDs (Mcp-Session-Id), SSE streaming, the MCP-Protocol-Version header and input validation. None of that is magic either. It’s the same conversation with more of the edge cases covered.

The guide has you rerun the Step 1 shell calls against the SDK server and compare the responses. That’s the payoff of doing it in this order: the SDK stops being a black box, because you already know what the request and response look like underneath.

What I built on top

The rest of the guide turns this into a real index over the vault. Briefly:

• Parsing. Notes are split into sections by heading, and each chunk is prefixed with the note title and heading so it still makes sense on its own. Wikilinks and tags are pulled out at the same time.
• Embeddings. Each section is embedded locally through Ollama with nomic-embed-text. That model expects task prefixes, so documents are embedded as search_document: … and queries as search_query: ….
• Storage and search. Vectors live in LanceDB, an embedded database. search_vault asks for more hits than it needs and keeps the best section per note, so one long note can’t fill every result.
• Backlinks. An in-memory map of wikilinks answers get_backlinks.
• Watching. A file watcher re-indexes notes as I edit them. It’s debounced, because Obsidian autosaves while you type and you don’t want to re-embed the same note over and over.
• Startup reconcile. Edits made while the server was off produce no watcher events, so on startup the server hashes every note and compares it with the stored hash. Only notes whose hash changed are re-embedded, and notes that disappeared are removed.

Watcher jobs and the reconcile run one at a time through a single promise chain:

js

let chain = Promise.resolve(); // serial queue: one job at a time

const enqueue = (job) => (chain = chain.then(job).catch((e) => console.error("index error:", e.message)));

That’s the whole queue. Its job is to stop two reindexes of the same note from running at once and deleting each other’s rows.

Safety choices for a server that touches personal files

This server reads my notes and can write files. It only runs on my own machine, but every argument a tool receives comes from a model, so I treated it as untrusted input.

Localhost only. The server binds to 127.0.0.1. A small middleware also rejects requests from any browser origin other than localhost, which guards against a web page using DNS rebinding to reach it.

Paths stay inside the vault. Every path is normalized to forward slashes and checked against the vault root:

js

export function resolveInVault(rel) {
    const abs = path.resolve(VAULT, ...normRel(rel).split("/"));
    const inside = path.relative(VAULT, abs);
    if (inside === ".." || inside.startsWith(".." + path.sep) || path.isAbsolute(inside))
        throw new Error("Path outside vault");
    return abs;
}

My first version compared string prefixes (abs.startsWith(VAULT + path.sep)). I replaced it with this path.relative check while adjusting the vault code for Windows path conventions. The new check also catches a path on another Windows drive, where path.relative returns an absolute path. The guide has you try ../../etc/passwd, an absolute path and a missing file against get_note. All three should come back as isError with the server still running.

One tool writes, and only new files. create_note can only create files in the inbox folder. The model supplies a title, never a path. The title is cleaned into a file name that’s valid on Windows, macOS and Linux: control characters and illegal characters are removed, leading dots are stripped, and reserved device names like CON get an underscore. The file is opened with the wx flag, so it fails with EEXIST instead of overwriting, and the tool tells the model to pick another title. There are no edit or delete tools. The tool doesn’t touch the index either; the watcher sees the new file and indexes it like any other edit.

No code in frontmatter. I started with gray-matter to parse YAML frontmatter, and replaced it because of CVE-2026-78847. gray-matter has a built-in JavaScript engine that runs ---js frontmatter through eval(), so any note dropped into the vault could execute code inside an always-on process. Obsidian frontmatter is always YAML, so I replaced it with a small parser around the yaml package:

js

// Optional BOM, "---", the YAML lines, closing "---"
const FM = /^?---\r?\n([\s\S]*?\r?\n)?---[ \t]*(?:\r?\n|$)/;

export function parseFrontmatter(raw) {
    const m = raw.match(FM);
    if (!m) return { data: {}, content: raw };
    let data = {};
    try {
        const parsed = YAML.parse(m[1] ?? "");
        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) data = parsed;
    } catch {
        // Malformed YAML: keep the body, treat frontmatter as empty
    }
    return { data, content: raw.slice(m[0].length) };
}

Only a plain --- line opens frontmatter, so a ---js block never matches. It’s just text. The guide includes a test: a note that starts with ---js and a console.log("pwned") line should come back with empty frontmatter and those lines as plain text, with nothing printed in the server window.

None of this makes the server safe to expose beyond localhost. That would need authentication and HTTPS, and the README says so.

The takeaway

If you’re starting with MCP, write the raw version once. The guide budgets 45 minutes for it: one file, no dependencies, a handful of calls from your shell. After that, the SDK reads as a convenience layer over a conversation you’ve already seen, and when something goes wrong you know which layer to look at.