Dev.to WebDev 🛠 Dev 👁 0 📖 3 min read

Making a personal website readable by AI agents: Markdown pages, llms.txt and an MCP server

Recruiters and engineers increasingly work through AI assistants. I wanted karthik.nz to give those assistants clean, approved text instead of 60 to 148 KB of HTML per page. This post covers what I added and the decision

Recruiters and engineers increasingly work through AI assistants. I wanted karthik.nz to give those assistants clean, approved text instead of 60 to 148 KB of HTML per page. This post covers what I added and the decisions behind each piece. The site is Next.js on Vercel, and the changes were made without altering what human visitors see.

1. One registry, Markdown for every page

src/lib/agent-docs.ts lists every page (home, resume, open source, each case study) with a title, a one-line summary and a Markdown builder. Everything below reads from that single registry.

  • Every page has a Markdown twin: /index.md, /resume.md, /open-source.md, /work/<slug>.md.
  • /llms.txt is an index of those pages, and /llms-full.txt is everything in one file.
  • A request with Accept: text/markdown gets the Markdown. Browsers never send that header, so they keep getting HTML.
  • Markdown responses carry Link: <page URL>; rel="canonical", so search engines index the HTML page and not its copy.

I considered converting the built HTML with a package, or hand-writing Markdown files. I chose to generate Markdown from the same content the pages render. A converter repeats navigation text and adds a dependency, and hand-written files drift out of date. With one source, the output can be checked.

That check is a script (agent-docs:check) run against a production build. It fails if the Markdown says anything the page does not. The Markdown comes to 2 to 7 KB per page, so an agent can read a whole page cheaply.

2. Telling agents the Markdown exists

  • Each HTML page sends a Link: <.../resume.md>; rel="alternate"; type="text/markdown" header. A header adds no bytes to the page and no work in the browser.
  • The curl card on the site gained one row pointing at /llms.txt.
  • IndexNow (a free protocol with a public key and no account) tells Bing about changed pages. Bing's index feeds ChatGPT search and Copilot. It runs by hand after a deploy.

3. A read-only MCP server

https://karthik.nz/mcp is a Streamable HTTP MCP server with no sign-in. It exposes five tools (get_profile, get_resume, list_projects, get_project, get_open_source) and one resource per page.

I used the official TypeScript SDK on its own, inside a Next.js route handler. Its transport takes a Request and returns a Response, which is exactly what a route handler is. Vercel's adapter would have added a package for nothing, and hand-written JSON-RPC would have missed protocol details the SDK handles. The server is stateless, with a fresh instance per request.

Because answers come from the same registry as the pages, the server cannot say anything the website does not. mcp:check connects with the SDK's own client, calls every tool, reads every resource and compares each answer to the matching Markdown page.

4. Listing it in the MCP Registry

The official registry requires a name in a namespace you can prove you own. I used nz.karthik/karthik-parameshwara, proven by a public key at /.well-known/mcp-registry-auth. That file deploys with the site, so no DNS change was needed. The private key stays on my machine and out of the repo.

What I'd flag as unverified

  • On Vercel, the rewrite that serves Markdown should run before the cache, so a browser cannot be served cached Markdown. I inferred this and did not measure it.
  • The server sends no CORS headers, so a browser-based client could not connect directly. Claude, ChatGPT and Cursor connect from their own apps or servers, but I have not tested each one.
  • Cold starts on a Vercel Hobby function are slower than the 7 to 28 ms I measured warm on a local build.

No search engine finds an MCP server on its own, so this is a convenience and a demonstration, not a ranking signal.

The site is at https://karthik.nz, and each decision is written up as an ADR in the repo.

📰 Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.