# Writing

Notes from my own research, for engineers building the same things: MCP servers, AI tooling for codebases, and the IoT and machine-learning work that came before.

- [Open-source personal agents in 2026: OpenClaw, Hermes Agent and four more, compared](https://pournasserian.com/writing/open-source-personal-agents-2026): Six open-source, always-on personal AI agents compared: OpenClaw, Hermes Agent, Nanobot, ZeroClaw, NanoClaw and IronClaw, and which fits what.
- [Visually validating vector data for RAG](https://pournasserian.com/writing/visually-validating-rag-vectors): How I inspect my website's embeddings with projection maps, exact neighbors and chunk diagnostics, and where visual checks need retrieval tests.
- [Two reference architectures for an MCP server: minimal cost and enterprise scale](https://pournasserian.com/writing/mcp-infrastructure-minimal-enterprise): Two reference architectures for the same MCP search service: a small Azure deployment and an Azure-only enterprise proposal, with diagrams and costs.
- [Decision models against small LLMs: Jev, Kev, Laya and Mammoth-1 on 6,662 decisions](https://pournasserian.com/writing/decision-models-vs-small-llms-2026): Four decision models and five small LLMs on the same 6,662 decisions: accuracy, calibration, format failures, latency and cost, every call published.
- [Validating a vector database built for RAG: four layers of checks, with the code to run them](https://pournasserian.com/writing/validating-a-vector-database-for-rag): How to check a RAG vector index on its own, in four layers from the chunks to the answer, with runnable Python and 25 evaluation tools compared.
- [RAG, CAG, KAG and the search beneath them: which fits which problem in 2026](https://pournasserian.com/writing/rag-cag-kag-retrieval-methods-2026): RAG, CAG, KAG and the search beneath them, from BM25 to graphs, compared on the published evidence, with a guide to which fits which problem.
- [How MCP extensions work](https://pournasserian.com/writing/mcp-2026-extensions): MCP extensions are optional additions, off by default: which exist in October 2026, how both sides negotiate them per request, and how a server falls back.
- [MCP Apps: how interactive UI gets into the conversation](https://pournasserian.com/writing/mcp-2026-apps): MCP Apps puts interactive HTML inside the chat: how the server, the host and the sandboxed view share the work, and the messages up to the first render.
- [Building an MCP App: declarations, sandbox and text fallbacks](https://pournasserian.com/writing/mcp-2026-apps-building): What an MCP App's server declares, how its view talks to the host, how web hosts sandbox it, and a Python tool with a text fallback plus a TypeScript view.
- [MCP Tasks: long-running work without holding a connection](https://pournasserian.com/writing/mcp-2026-tasks): How the MCP Tasks extension answers a tool call with a task the client polls: its states and methods, durable storage, security, and a Python type.
- [Skills over MCP: shipping workflows with your server](https://pournasserian.com/writing/mcp-2026-skills): How an MCP server publishes Agent Skills over skills/list and skills/get, the SHA-256 manifest hosts verify, when approval applies, and a Python builder.
- [Enterprise-managed authorization and client credentials for MCP](https://pournasserian.com/writing/mcp-2026-enterprise-auth): Two official MCP authorization extensions: enterprise access through an ID-JAG from the company's IdP, and client credentials for jobs with no user.
- [Experimental and vendor-specific MCP extensions](https://pournasserian.com/writing/mcp-2026-experimental-extensions): What vendor _meta keys like anthropic/alwaysLoad do, why they must stay optional, what Interceptors and Variants propose, and when to build your own.
- [One request through an MCP server, end to end](https://pournasserian.com/writing/mcp-2026-end-to-end): One MCP request followed through seven phases, from server/discover to the app's teardown, then tested in Python with a fake host and a wire recorder.
- [Which AI hosts support which MCP features (October 2026)](https://pournasserian.com/writing/mcp-2026-host-support): Which MCP features Claude, Claude Code, ChatGPT, VS Code, Cursor, Gemini CLI and Microsoft 365 Copilot support, and what that means for your server.
- [MCP server design patterns and anti-patterns](https://pournasserian.com/writing/mcp-2026-design-patterns): Four MCP server design patterns that hold up, from search plus fetch to layered surfaces, and the twelve anti-patterns behind most production problems.
- [Should you put an AI agent behind an MCP tool?](https://pournasserian.com/writing/mcp-2026-agent-behind-a-tool): When an inner agent behind an MCP tool helps, when plain search and fetch tools serve the calling model better, and eleven design rules if you build one.
- [A reference architecture for MCP servers in production](https://pournasserian.com/writing/mcp-2026-reference-architecture): How the 2026 MCP duties shape a production deployment: a generic architecture, one way to host it on Azure, and a build pipeline for MCP's own artifacts.
- [The MCP server author's checklist](https://pournasserian.com/writing/mcp-2026-server-checklist): A one-page checklist for MCP server authors, from server/discover to deprecations, each item linked to the series article that explains it.
- [What to require from an MCP server vendor: a buyer's checklist](https://pournasserian.com/writing/mcp-buyer-vendor-requirements): The questions to put to an MCP server vendor before you sign, drawn from the 2026-07-28 specification, and what a good answer to each looks like.
- [An MCP governance checklist for the CTO](https://pournasserian.com/writing/mcp-buyer-governance-checklist): The decisions a CTO has to make before MCP servers reach a company's AI tools, from who controls each primitive to what the host must enforce.
- [MCP maturity in October 2026: what's stable, what's deprecated, what's still a bet](https://pournasserian.com/writing/mcp-buyer-maturity-map): Which parts of MCP a buyer can rely on in October 2026: five revisions of the specification, what 2026-07-28 removed, and where each extension stands.
- [MCP host coverage: will the server work in the AI apps your company uses?](https://pournasserian.com/writing/mcp-buyer-host-coverage): Tools on a remote server are the only MCP surface all seven hosts support, so check a server against the AI apps your company runs before you buy it.
- [Your MCP server is an OAuth resource server: what it must do](https://pournasserian.com/writing/mcp-2026-oauth-resource-server): An MCP server is an OAuth 2.1 resource server with four duties: publish its metadata, send the 401, validate every token, and forward none of them.
- [MCP authorization in practice: step-up, no passthrough, Entra ID](https://pournasserian.com/writing/mcp-2026-oauth-step-up-and-entra): How an MCP server asks for more scope with a 403 step-up, calls other APIs without passing tokens through, and works with Microsoft Entra ID.
- [Tracing MCP calls with OpenTelemetry](https://pournasserian.com/writing/mcp-2026-opentelemetry): How an MCP server continues a trace from traceparent in _meta, which spans and attributes to emit, what to measure, and what the Python SDK traces for you.
- [An MCP threat model: what to defend, and where](https://pournasserian.com/writing/mcp-2026-threat-model): The threats an MCP deployment faces, from tool poisoning to token passthrough, its three trust boundaries, what the spec requires, and layers of defence.
- [Serving two MCP protocol eras: deprecations and a migration checklist](https://pournasserian.com/writing/mcp-2026-migration-two-eras): How one MCP server serves 2025-era and 2026-07-28 clients at once, what is deprecated and until when, what is gone, and a migration checklist.
- [Multi round-trip requests: how a stateless MCP server asks for more](https://pournasserian.com/writing/mcp-2026-multi-round-trip-requests): How a stateless MCP server asks for a confirmation without a session: the input_required result, the retry, the rules for both sides, and a Python example.
- [requestState: sealing the state your MCP server hands to the client](https://pournasserian.com/writing/mcp-2026-request-state): Why an MCP server must seal the requestState it hands the client, what to bind into it, what the Python SDK seals for you, and how to build a wizard on it.
- [Elicitation in MCP: asking the user with a form or a link](https://pournasserian.com/writing/mcp-2026-elicitation): How an MCP server asks the user through the host: form and URL elicitation in multi round-trip requests, capability checks, and a sign-in link in Python.
- [Progress, cancellation and timeouts when nothing can resume](https://pournasserian.com/writing/mcp-2026-progress-and-cancellation): How an MCP server reports progress, honours cancellation on stdio and Streamable HTTP, and lives with timeouts when a dropped stream can't resume.
- [subscriptions/listen: change notifications in MCP](https://pournasserian.com/writing/mcp-2026-subscriptions-listen): How an MCP server streams change notifications with subscriptions/listen: the filter, acknowledgement first, reconnects and fan-out across instances.
- [Open-source AI chat apps in 2026: 51 mapped, 12 compared, and which fits what](https://pournasserian.com/writing/open-source-ai-chat-apps-2026): Fifty-one open-source alternatives to the ChatGPT and Claude apps, mapped by GitHub stars and activity, twelve compared, and a pick for eight uses.
- [Making a website AI friendly: what the bots actually fetched from mine](https://pournasserian.com/writing/ai-friendly-website-2026): What AI crawlers actually fetched from this site in 18 days: pages, robots.txt and the sitemap most of all, and llms.txt never by a verified crawler.
- [An LLM-friendly website checklist: eight steps and a test for each](https://pournasserian.com/writing/llm-friendly-website-checklist): Eight steps to make a website easy for AI crawlers and agents to read, in the order the bots fetched them, each with a command to check your own site.
- [Designing an MCP tool: the definition and the result](https://pournasserian.com/writing/mcp-2026-tool-definitions): What an MCP tool definition and its result carry: naming rules, annotations, content and structuredContent, with a Python weather tool.
- [MCP tool errors, and tools that models use well](https://pournasserian.com/writing/mcp-2026-tool-errors-and-design): When an MCP tool should return isError and when a protocol error, what the Python SDK does with exceptions, and how to design tools models use well.
- [MCP resources: context the application decides to use](https://pournasserian.com/writing/mcp-2026-resources): How an MCP server lists and reads resources and URI templates, the error a missing resource gets, and what hosts and the Python SDK do with them.
- [MCP prompts: slash commands your server ships](https://pournasserian.com/writing/mcp-2026-prompts): How MCP prompts work: how hosts invoke them, prompts/list and prompts/get, argument completion, safe arguments and a Python example.
- [Tool, resource or prompt? Choosing the right MCP primitive](https://pournasserian.com/writing/mcp-2026-choosing-a-primitive): Tools, resources and prompts differ in who decides when they're used: how to pick an MCP primitive, and where instructions, Skills, Apps and Tasks fit.
- [What an MCP server does in 2026: much more than a list of tools](https://pournasserian.com/writing/mcp-2026-what-a-server-does): What an MCP server does in 2026: three roles, duties against features and extensions, one request traced through, and a one-tool Python server.
- [MCP goes stateless: what changed in the 2026-07-28 specification](https://pournasserian.com/writing/mcp-2026-what-changed): The 2026-07-28 MCP spec drops the handshake, sessions and server-initiated requests: what replaces them, what else changed, and what is deprecated.
- [server/discover: the one method every MCP server must implement](https://pournasserian.com/writing/mcp-2026-server-discover): server/discover is the one method every 2026-07-28 MCP server must implement: what it returns, and how a client negotiates a version or falls back.
- [Server instructions: the paragraph every model reads first](https://pournasserian.com/writing/mcp-2026-server-instructions): What MCP server instructions are, how hosts such as Claude Code load them, and what to write and what to leave out, with a Python example.
- [Stateless MCP requests: _meta, resultType and explicit handles](https://pournasserian.com/writing/mcp-2026-stateless-requests): Every 2026-07-28 MCP request carries its version and capabilities in _meta: how a client branches on resultType and how a server keeps state in handles.
- [Caching hints and pagination in MCP](https://pournasserian.com/writing/mcp-2026-caching-and-pagination): Six MCP methods' results must carry ttlMs and cacheScope: how the caching hints work, why tool order should stay stable, and how cursor pagination works.
- [MCP transports in 2026: stdio and Streamable HTTP](https://pournasserian.com/writing/mcp-2026-transports): How MCP's two transports work: stdout on stdio, the headers that route a Streamable HTTP request, x-mcp-header, and proxy timeouts.
- [MCP servers for websites in 2026: 44 tools, sorted by who runs them](https://pournasserian.com/writing/mcp-servers-for-websites-2026): Forty-four ways to let an AI agent search and ask a website over MCP, from Wix and Shopify to NLWeb and CMS plugins, sorted by who runs the server.
- [AI tools that document a codebase in 2026: 17 compared, and what none of them does yet](https://pournasserian.com/writing/ai-code-documentation-tools-2026): Seventeen tools that turn a repository into documentation, compared on what each reads and produces and who it serves, and the gaps none of them fills.
- [Observed, documented, inferred: a design for codebase documentation you can audit](https://pournasserian.com/writing/evidence-labelled-code-documentation): A design for documentation generated from code where every fact carries evidence and a label, observed, documented or inferred, so readers can audit it.
- [Testing MCP servers in 2026: 31 tools compared and the gaps between them](https://pournasserian.com/writing/mcp-server-testing-tools-2026): Thirty-one tools that inspect, test, audit, secure or load test an MCP server, compared on twelve capabilities, and the gaps none of them fills.
- [One MCP server, eight rulebooks: what the spec, Claude, ChatGPT, Codex, VS Code, Windsurf, Kiro and Gemini CLI require](https://pournasserian.com/writing/what-ai-hosts-require-of-an-mcp-server): The checkable rules each AI host applies to an MCP server, from tool-name length to mandatory annotations, where they conflict, and what validates them.
- [Getting IoT device data to the cloud: webhooks, device management and testing](https://pournasserian.com/writing/iot-webhooks-device-management-testing): How a webhook carries sensor data, what managing a fleet of IoT devices involves, and what to test before a full deployment. From 2018.
- [Bluetooth Low Energy fundamentals: how it saves power and reaches the internet](https://pournasserian.com/writing/bluetooth-low-energy-fundamentals): How Bluetooth Low Energy saves power, which devices can talk to which, how a sensor reaches the internet, and what mesh adds, as it stood in 2018.
- [BLE beacons in practice: protocols, sensors, layout and transmission power](https://pournasserian.com/writing/ble-beacons-in-practice): Four decisions in a Bluetooth beacon deployment, from 2018: iBeacon or Eddystone, which sensors, point or grid layout, and how much transmission power.
- [Indoor location: RTLS, asset tracking, beacons and ultra-wideband](https://pournasserian.com/writing/indoor-location-rtls-beacons-uwb): What makes a tracking system real-time, which technologies an RTLS can run on, and when to choose Bluetooth beacons or ultra-wideband, from 2018.
- [Recognizing handwritten digits: six neural networks on MNIST, from 92% to 99.4%](https://pournasserian.com/writing/mnist-handwritten-digit-recognition): Six TensorFlow models for the MNIST digits, from 2017: one softmax layer at 92%, up to a convolutional network with batch normalization at 99.4%.
- [A first try at sentiment analysis: TextBlob on a Twitter stream](https://pournasserian.com/writing/twitter-sentiment-textblob-tweepy): A weekend experiment from January 2017: reading a live Twitter stream with Tweepy and scoring each tweet with TextBlob, in about thirty lines of Python.
