DEV Community: Ali Ibrahim

5 Agent Skills I’d install before starting any new agent project in 2026

Ali Ibrahim — Mon, 16 Mar 2026 14:44:21 +0000

Your coding agent can write code, refactor functions, and debug errors. But can it design production-grade prompts? Build MCP servers that follow best practices? Evaluate whether your agent's outputs are actually good?

Agent Skills give your coding assistant specialized expertise on demand. They're folders containing a SKILL.md file with instructions, workflows, and references that your agent loads only when relevant. No context bloat, no manual setup. For a deep dive into how skills work and how to build your own, see How to Build and Deploy an Agent Skill from Scratch.

Here are 5 skills that cover the full agent development lifecycle, from designing prompts to evaluating outputs. Every skill listed works across Claude Code, Cursor, VS Code Copilot, Codex, and Gemini CLI.

To install any skill, run:

npx skills add <owner/repo> --skill <skill-name>

1. prompt-engineer

An expert prompt engineering skill that teaches your agent advanced techniques for designing effective LLM prompts. It covers system prompt architecture, few-shot example design, chain-of-thought patterns, output format specification, and context management. The skill identifies common pitfalls like imprecise language, missing format constraints, and prompt injection vulnerabilities.

Why it matters: Prompt design is the highest-leverage activity in agent development. A well-crafted prompt can be the difference between a prototype and a production-ready agent. This skill turns your coding assistant into a prompt engineering partner that catches issues before they reach users.

Best for: Any developer writing or refining prompts for LLM-powered applications and agents.

npx skills add davila7/claude-code-templates --skill prompt-engineer

GitHub: davila7/claude-code-templates

For Anthropic's approach to agent-specific prompting, see The Art of Agent Prompting.

2. skill-creator

Anthropic's official skill for creating, modifying, and evaluating skills. Instead of starting from a blank SKILL.md, this skill guides your agent through an iterative development cycle: define intent, draft the skill file, test with sample prompts, evaluate outputs, and refine. It adapts to different environments (Claude.ai, Claude Code, Cursor) and supports users across technical expertise levels.

Why it matters: Building skills manually is educational but slow. This skill automates the creation process and includes built-in evaluation with variance analysis, helping you ship higher-quality skills faster.

Best for: Developers who want to create custom skills for their team, product, or domain without starting from scratch.

npx skills add anthropics/skills --skill skill-creator

GitHub: anthropics/skills

For the manual approach that teaches you every component, see How to Build and Deploy an Agent Skill from Scratch.

3. mcp-builder

Anthropic's official guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services. The skill covers the full development cycle in four phases: research and planning, implementation, review and testing, and evaluation creation. It supports both Python (FastMCP) and TypeScript implementations, and emphasizes concise tool descriptions and actionable error messages.

Why it matters: Skills give agents knowledge; MCP servers give agents capabilities. If you need your agent to interact with APIs, databases, or external services, this skill teaches it how to build MCP servers that follow best practices.

Best for: Developers building custom MCP servers to extend their agents' capabilities.

npx skills add anthropics/skills --skill mcp-builder

GitHub: anthropics/skills

For a quick hands-on start with MCP, see Create Your First MCP Server in 5 Minutes.

4. agentic-eval

Patterns and techniques for evaluating and improving AI agent outputs through iterative refinement. This skill teaches your agent to implement self-critique loops, evaluator-optimizer pipelines, rubric-based assessment, and LLM-as-judge evaluation systems. Rather than relying on single-shot generation, it introduces systematic approaches to measuring and improving output quality.

Why it matters: Building an agent is half the challenge. Knowing whether it works reliably is the other half. This skill teaches your coding assistant how to evaluate agent outputs systematically, a practice that separates prototype-quality agents from production-ready ones.

Best for: Developers testing, debugging, or improving agent output quality, especially when building evaluation pipelines.

npx skills add github/awesome-copilot --skill agentic-eval

GitHub: github/awesome-copilot

5. openai-docs

Provides up-to-date OpenAI developer documentation with citations, covering the Responses API, Agents SDK, Chat Completions, Codex, Realtime API, model capabilities, and more. The skill uses OpenAI's MCP server to search, fetch, and browse official documentation pages, prioritizing MCP tools over general web search for accuracy.

Why it matters: LLM training data goes stale. If you are building with OpenAI APIs, this skill ensures your agent references the latest documentation rather than outdated knowledge. Every answer comes with a citation to the official source.

Best for: Developers building with OpenAI APIs who need accurate, current references without leaving their IDE.

npx skills add openai/skills --skill openai-docs

GitHub: openai/skills

Bonus: ai-sdk

The top 5 skills above are broadly useful to any agent builder regardless of stack. This bonus is more specialized, but for its audience, it may be the most valuable skill on this list.

The ai-sdk skill answers questions about the Vercel AI SDK and helps build AI-powered features. It covers core functions like generateText, streamText, ToolLoopAgent, embed, and tool calling. The skill checks local node_modules/ai/docs/ first, then falls back to ai-sdk.dev for the latest information.

Why it matters: The AI SDK is the most downloaded TypeScript AI framework with 2.8M weekly npm downloads. If you're building AI features in a Next.js or React application, this skill makes your coding assistant an AI SDK expert.

Best for: React and Next.js developers integrating AI features using the Vercel AI SDK.

npx skills add vercel/ai --skill ai-sdk

GitHub: vercel/ai

Quick Reference

Skill	Best For	Created By
prompt-engineer	Writing effective LLM prompts	Community (davila7)
skill-creator	Creating and iterating on skills	Anthropic
mcp-builder	Building MCP servers	Anthropic
agentic-eval	Evaluating agent outputs	GitHub
openai-docs	OpenAI API documentation	OpenAI
ai-sdk (Bonus)	Vercel AI SDK development	Vercel

Key Takeaways

These 5 skills cover the full agent development lifecycle: design prompts, package expertise, build tools, evaluate quality, and reference documentation.
All skills are cross-platform. They work across Claude Code, Cursor, VS Code Copilot, Codex, and Gemini CLI.
Combine skills for compound effect. Use prompt-engineer to design your agent's prompts, skill-creator to package your expertise, and agentic-eval to verify quality.
Vet skills before installing. Prefer skills published by known organizations like Anthropic, GitHub, or OpenAI. For community skills, check their detail page on skills.sh: every listed skill displays a Security Audit report so you know what you're installing.
The skills ecosystem is growing fast. Browse skills.sh regularly to discover new skills as they are published.

What to Read Next

Enjoying content like this? Sign up for Agent Briefings, where I share insights and news on building and scaling AI agents.

Resources

Securing MCP Servers: A Practical Guide with Keycloak (using create-mcp-server)

Ali Ibrahim — Tue, 03 Mar 2026 14:30:00 +0000

Introduction

MCP servers are powerful. They let AI agents interact with databases, APIs, file systems, and virtually anything you can imagine. But there's a catch: most tutorials show you how to build MCP servers without authentication.

That's fine for local development. It's a problem for production.

An unsecured MCP server is an open door. Anyone who discovers your endpoint can invoke your tools, access your resources, and potentially wreak havoc on your systems. As MCP adoption grows and servers move from localhost to cloud deployments, security isn't optional anymore.

The good news? The MCP Authorization specification provides a standard way to secure MCP servers using OAuth 2.1. And with the right tools, implementing it is straightforward.

In this guide, you'll learn:

How MCP authorization works (without the jargon)
How to scaffold a secure MCP server with create-mcp-server
How to set up Keycloak as your OIDC provider
How to test your authenticated server with VS Code, Cursor and a terminal client

Let's lock down your MCP server.

Understanding MCP Authorization

If you're new to MCP, here's the short version: the Model Context Protocol is an open standard that lets AI assistants discover and use external tools. Think of it as a universal adapter between AI models and the real world. For a deeper dive, check out our article on running MCP servers with Docker.

Why Security Matters

When you deploy an MCP server, you're exposing capabilities to the network. Those capabilities might include:

Reading and writing to databases
Sending emails or notifications
Accessing internal APIs
Managing cloud resources

Without authentication, anyone can call these tools. That's why the MCP specification includes authorization as a core feature.

OAuth: The Hotel Key Card

OAuth might sound intimidating, but the concept is simple. Think of it like a hotel key card system:

You check in at the front desk (authentication)
You receive a key card (access token)
You use the key card to access your room (authorized requests)
The door checks if your card is valid (token validation)

That's OAuth in a nutshell. The MCP client gets a token from an authorization server, then includes that token with every request. The MCP server validates the token before granting access.

The MCP specification requires OAuth 2.1 with PKCE (Proof Key for Code Exchange), which adds an extra security layer to prevent token interception. You don't need to understand the cryptographic details, just know that it's a modern, secure approach.

Dynamic Client Registration (DCR)

Here's something important that often gets overlooked: Dynamic Client Registration.

In traditional OAuth setups, you manually register each client application with your authorization server. You create a client, get a client ID and secret, and configure them in your app. This works fine when you have a handful of known clients.

But MCP is different. The whole point is that any MCP-compatible client should be able to connect to your server. Claude Desktop, VS Code, Cursor, custom agents, there could be dozens of different clients trying to connect.

DCR solves this. It allows clients to register themselves automatically with the authorization server. No manual setup required. The client says "hey, I'd like to connect," and the server says "here are your credentials."

This is critical for the MCP ecosystem to scale. And it's one of the main reasons we're using Keycloak: Keycloak fully supports Dynamic Client Registration. Not all OIDC providers do. If you're evaluating alternatives like Auth0, Azure AD, or Okta, check their DCR support carefully.

For the complete technical specification, see the MCP Authorization documentation.

Introducing create-mcp-server

Building an MCP server from scratch with OAuth is tedious. You need to set up Express, configure middleware, handle token validation, manage sessions, and wire up SSE for real-time updates. That's hours of boilerplate before you write a single tool.

create-mcp-server eliminates that friction. It's a CLI tool that scaffolds production-ready MCP servers in seconds:

npx @agentailor/create-mcp-server

The CLI walks you through a few questions and generates a complete project with TypeScript, Express.js, and optionally OAuth authentication baked in.

Two Templates

Feature	Stateless	Stateful
Session management	—	✓
SSE support	—	✓
OAuth option	—	✓
Endpoints	POST /mcp	POST, GET, DELETE /mcp

Stateless: Each request creates a new transport instance. Simple, but no session persistence.

Stateful: Sessions are maintained across requests. Supports Server-Sent Events for real-time updates. This is what you need for OAuth.

For this guide, we'll use the Stateful template with OAuth enabled.

Scaffolding Your Secure MCP Server

Let's create our server. Run the CLI and answer the prompts:

npx @agentailor/create-mcp-server@0.2.1

Note: If you are using v0.3.0 or later, you'll have a new prompt for selecting a framework. To follow this article, you should select the official SDK.

When prompted:

Enter (y) for npx to download the package
Project name: my-secure-mcp-server
Template: Stateful
Enable OAuth: Yes
Package manager: Your preference (npm, pnpm, or yarn)

The CLI generates this structure:

my-secure-mcp-server/
├── src/
│   ├── server.ts     # MCP server (tools, prompts, resources)
│   ├── index.ts      # Express app and transport setup
│   └── auth.ts       # OAuth middleware
├── package.json
├── tsconfig.json
├── .gitignore
├── .env.example
└── README.md

Key Files Explained

src/server.ts: This is where you define your MCP tools, prompts, and resources. It's the "business logic" of your server.

src/index.ts: The Express application. It sets up routes, applies middleware, and manages the HTTP transport.

src/auth.ts: The OAuth middleware. This is provider-agnostic, it works with any OIDC-compliant authorization server. You configure the provider through environment variables.

.env.example: Template for required environment variables:

PORT=3000

# OAuth Configuration
# Issuer URL - your OAuth provider's base URL
# Examples:
#   Auth0: https://your-tenant.auth0.com
#   Keycloak: http://localhost:8080/realms/your-realm
OAUTH_ISSUER_URL=https://your-oauth-provider.com

# Audience - the API identifier (optional, but recommended)
# This should match the "aud" claim in your JWT tokens
OAUTH_AUDIENCE=https://your-mcp-server.com

Install dependencies and you're ready to configure Keycloak:

cd my-secure-mcp-server
npm install

Setting Up Keycloak

We're using Keycloak as our OIDC provider. Here's why:

Open-source: No vendor lock-in, full transparency
OIDC-compliant: Works with any OAuth 2.1 / OpenID Connect client
Supports DCR: Dynamic Client Registration out of the box
Self-hosted: Complete control over your auth infrastructure
Battle-tested: Used by enterprises worldwide

Running Keycloak with Docker

From your terminal, run the following command to start the Keycloak container:

docker run -p 127.0.0.1:8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak start-dev

Wait a minute for startup, then access the admin console at http://localhost:8080.

Configuring Keycloak

1. Create a Realm

Click on "Manage realms" in the top-left sidebar
Click Create realm
Name it mcp-realm
Click Create

2. Create a Client

Go to Clients → Create client
Client ID: mcp-server-client
Client authentication: Enable (this makes it confidential)
Leave redirect URIs empty (we'll update later if needed)
Click Save

Environment Variables

Update/create your .env file with the Keycloak values:

PORT=3000

OAUTH_ISSUER_URL=http://localhost:8080/realms/mcp-realm
OAUTH_AUDIENCE= #leave empty for Keycloak

3. Create a Test User

Go to Users → Add user
Username: testuser
Set Email verified to ON
Click Create
Go to Credentials tab → Set password
Enter a password and disable "Temporary"

Connecting MCP Server to Keycloak

With Keycloak running and your .env configured, start your MCP server:

npm run dev

You should see output like:

[auth] Validating OAuth configuration for issuer: http://localhost:8080/realms/mcp-realm
[auth] Successfully fetched OIDC discovery document
[auth] Authorization endpoint: http://localhost:8080/realms/mcp-realm/protocol/openid-connect/auth
[auth] Token endpoint: http://localhost:8080/realms/mcp-realm/protocol/openid-connect/token
[auth] JWKS URI: http://localhost:8080/realms/mcp-realm/protocol/openid-connect/certs
[auth] JWKS endpoint is accessible
[auth] OAuth configuration validated successfully
MCP Stateful HTTP Server listening on port 3000
OAuth metadata available at http://localhost:3000/.well-known/oauth-protected-resource

The auth middleware automatically:

Intercepts incoming requests
Extracts the Bearer token from the Authorization header
Validates the token against Keycloak's JWKS endpoint
Rejects requests with invalid or missing tokens

Your server is now protected. Unauthenticated requests will receive a 401 Unauthorized response.

Testing Your Secure MCP Server

Let's verify everything works. We'll test with three methods: VS Code integration, Cursor integration, and a terminal client.

Setting Redirect URIs for VS Code and Cursor

In Keycloak, go to Clients → mcp-server-client → Settings
Under Valid Redirect URIs, add the following URIs:

cursor://anysphere.cursor-mcp/oauth/callback
https://vscode.dev/redirect/*
http://127.0.0.1:33418/* # this may vary based on your setup

Click Save

Note: If you have an error of "Invalid redirect URI", double-check the URIs match exactly or add missing ones.

VS Code Integration

VS Code supports MCP servers with OAuth authentication. Create a .vscode/mcp.json file in your project:

{
  "servers": {
    "my-secure-mcp-server": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

On top of the server name you'll see "Start":

VS Code will try to connect to your MCP server
If it detects OAuth, it initiates the authorization flow
If DCR is supported, it registers the client dynamically, otherwise it will prompt you to enter client details
You log in with your Keycloak credentials
VS Code receives the token and connects to your server

Your MCP tools are now available through VS Code's Copilot.

Cursor Integration

Cursor also supports MCP with OAuth. In Cursor, add a new MCP server:

Go to Cursor settings → Tools & MCP → New MCP Server
Enter the following details:

{
  "mcpServers": {
    "oauth-server": {
      "url": "http://localhost:3000/mcp",
      "auth": {
        "CLIENT_ID": "mcp-server-client",
        "CLIENT_SECRET": "<your-client-secret | EMPTY it's optional>",
        "scopes": ["mcp:tools"]
      }
    }
  }
}

After saving, go back to Tools & MCP and click on "Connect" next to your new server.
Cursor will open a browser window for you to log in via Keycloak.
After logging in, Cursor will receive the access token and connect to your MCP server.

Terminal Client Testing

The terminal client uses Dynamic Client Registration (DCR) to connect to your MCP server. This requires additional Keycloak configuration that wasn't needed for VS Code or Cursor (which use predefined clients).

Enabling Dynamic Client Registration in Keycloak

For DCR to work, Keycloak needs to trust the host where your client is running:

In Keycloak, go to Clients → Client registration → Trusted Hosts
Disable the Client URIs Must Match setting
Add your testing host's IP address to the trusted hosts list

To find your host IP:

Linux/macOS: Run ifconfig in your terminal
Windows: Run ipconfig in Command Prompt

If you're unsure which IP to add, check the Keycloak logs for a line like Failed to verify remote host : 192.168.x.x. That's the IP you need to whitelist.

Creating the mcp:tools Scope

The terminal client requires a custom scope to access MCP tools. Without this, authentication will succeed but tool access will fail.

In Keycloak, go to Client scopes → Create client scope
Name: mcp:tools
Type: Set to Default (so it's automatically included)
Include in token scope: Enable this toggle (required for token validation)
Click Save

Running the Terminal Client

Now you can test with the mcp-oauth-client:

git clone https://github.com/IBJunior/mcp-oauth-client
cd mcp-oauth-client
npm install
npm run build

Configure the client with your server and Keycloak details, then run:

npm run dev

The client will:

Use DCR to register itself with Keycloak automatically
Perform the OAuth flow
Obtain an access token (if the browser doesn't open automatically, copy-paste the URL from the console)

Connect to your MCP server
List available tools
Allow you to invoke tools interactively

This is useful for debugging and verifying your setup works end-to-end.

Adding Custom Tools

The scaffolded server comes with example tools. Let's add a custom one to see how easy it is.

Open src/server.ts and add a new tool:

server.registerTool(
  'greet',
  {
    description: 'Greets a user in their preferred language.',
    inputSchema: {
      name: z.string().describe("The user's name"),
      language: z.enum(['en', 'es', 'fr']).optional().describe('Greeting language'),
    },
  },
  async ({ name, language = 'en' }) => {
    const greetings = {
      en: `Hello, ${name}! Welcome to the secure MCP server.`,
      es: `¡Hola, ${name}! Bienvenido al servidor MCP seguro.`,
      fr: `Bonjour, ${name}! Bienvenue sur le serveur MCP sécurisé.`,
    }

    return {
      content: [
        {
          type: 'text',
          text: greetings[language],
        },
      ],
    }
  }
)

That's it. Restart your server and the new tool is available, automatically protected by OAuth. No additional authentication code required per tool. The middleware handles everything at the request level.

Using MCP Inspector

MCP Inspector is a debugging UI for MCP servers. It lets you explore available tools, test invocations, and inspect responses.

The scaffolded project includes an inspect script:

npm run inspect

Important caveat: For authenticated servers, you'll need to manually setup the oauth flow in MCP Inspector.

Recap

Let's summarize what we've covered:

What	Why
MCP Authorization	Industry standard for securing MCP servers
OAuth 2.1 + PKCE	Modern, secure token-based authentication
Dynamic Client Registration	Allows any MCP client to connect without manual setup
Keycloak	Open-source, OIDC-compliant, supports DCR
create-mcp-server	Fast scaffolding with authentication built-in
OIDC abstraction	Swap providers via environment variables

The key insight: security doesn't have to be complicated. With the right tools and a clear understanding of the concepts, you can go from zero to a production-ready, authenticated MCP server in minutes.

Conclusion

You've built a production-ready MCP server with OAuth authentication. Your tools are protected, tokens are validated, and you're following the MCP Authorization specification.

But here's the best part: Keycloak is just one option.

Because create-mcp-server uses a provider-agnostic OIDC implementation, you can swap Keycloak for any compliant provider. Just update your environment variables and you're done. That's the power of standards-based authentication.

A note on production deployments: The Keycloak configuration in this guide is designed for demonstration purposes. A production setup requires additional hardening: HTTPS everywhere, stricter redirect URI validation, token lifetime tuning, proper realm and client policies, and more. For production-grade configuration, refer to the official Keycloak documentation.

Next Steps

Star create-mcp-server on GitHub
Contribute to create-mcp-server
Explore the mcp-oauth-client for testing

Enjoying content like this? Sign up for Agent Briefings, where I share insights and news on building and scaling MCP Servers and AI agents.

Resources

create-mcp-server v0.6.0 is out, now with stdio transport support

Ali Ibrahim — Thu, 26 Feb 2026 20:22:59 +0000

Until now, the CLI only scaffolded Streamable HTTP servers (remote, cloud-deployable). But a lot of people build local MCP servers for Claude Desktop and other local clients — and stdio is the right transport for that.

So I added it.

npx @agentailor/create-mcp-server --name=my-server --stdio

That's it. No HTTP server, no port, no Dockerfile. Just a clean stdio server ready to connect to any local MCP client.

You can also combine it with FastMCP:

npx @agentailor/create-mcp-server --name=my-server --stdio --framework=fastmcp

What the CLI now supports:
→ HTTP (Streamable) or stdio transport
→ Official MCP SDK or FastMCP
→ Stateless or stateful server modes
→ Optional OAuth (SDK + HTTP)
→ npm, pnpm, or yarn

📚 Learning Resources

If you're getting started with MCP servers, here are the guides I've written:

→ Build your first MCP server in 5 minutes
https://blog.agentailor.com/posts/create-your-first-mcp-server-in-5-minutes

→ Secure your MCP server with OAuth (Keycloak)
https://blog.agentailor.com/posts/oauth-for-mcp-servers-practical-guide-keycloak

→ Getting started with FastMCP
https://blog.agentailor.com/posts/getting-started-with-fastmcp

→ OAuth for MCP Clients (Next.js + LangGraph.js)
https://blog.agentailor.com/posts/mcp-client-oauth-nextjs-langgraph

Star the repo if this is useful 🙏
https://github.com/agentailor/create-mcp-server

Deploy Your MCP Server to Google Cloud Run (For Free)

Ali Ibrahim — Mon, 23 Feb 2026 18:47:58 +0000

Introduction

You've built an MCP server. It works on localhost. Your AI assistant can call tools, fetch data, and do useful things, as long as everything runs on your machine.

But what happens when you want to share it with your team? Or connect to it from a different device? Or just keep it running without your laptop open?

You need to deploy it.

This guide walks you through deploying a Streamable HTTP MCP server to Google Cloud Run, from scaffolding to a live URL in minutes. Streamable HTTP is the transport designed for remote deployments: it works over standard HTTPS, plays nicely with load balancers, and doesn't require the client to run your server as a subprocess.

Note: If you're working with a stdio MCP server, the deployment path is different. We'll cover that briefly at the end of this article.

If you've already built an MCP server using our first MCP server guide, you can deploy that project directly. Otherwise, we'll scaffold a fresh one below.

What you'll learn:

How to scaffold a deployment-ready MCP server
How to set up the Google Cloud CLI
How to deploy to Cloud Run with a single command
How to test your live server with MCP Inspector

Prerequisites:

Node.js 20 or later
A Google Cloud account (free to create)
Basic terminal familiarity

Why Google Cloud Run?

Cloud Run can deploy from a container image, a Dockerfile, or even raw source code (using buildpacks). The create-mcp-server scaffold includes a Dockerfile, so that's the path we'll use. If you're bringing your own server, any of these options work.

Here's why Cloud Run is a great fit for MCP servers:

Generous free tier — 2 million requests/month, 180,000 vCPU-seconds, and 360,000 GiB-seconds of memory. More than enough for development, testing, and light production use.
Build from source — No need to install Docker locally. Cloud Run uses Cloud Build to build your Dockerfile remotely.
HTTPS by default — Every deployed service gets an HTTPS URL automatically. MCP clients expect HTTPS for remote servers.
Scale to zero — When no one is calling your server, it scales down to zero instances. You pay nothing when idle.
No code changes — Streamable HTTP servers work as-is on Cloud Run. The POST /mcp endpoint maps directly to Cloud Run's request-based model.

In short: you get a free, secure, production-ready deployment with almost zero configuration.

Scaffold Your MCP Server

If you already have an MCP server project with a Dockerfile, skip ahead to Set Up the gcloud CLI.

Otherwise, let's scaffold a fresh one. Run:

# For more options, see https://github.com/agentailor/create-mcp-server
npx @agentailor/create-mcp-server --name=my-mcp-server

This creates a stateless MCP server using the Official TypeScript SDK. No interactive prompts, no choices needed. One command, one project.

We're using a stateless server here for simplicity, but you can deploy a stateful server to Cloud Run the same way. The deployment steps are identical.

The generated project structure:

my-mcp-server/
├── src/
│   ├── server.ts     # MCP server (tools, prompts, resources)
│   └── index.ts      # Express app and HTTP transport
├── Dockerfile        # Production-ready Docker build
├── package.json
├── tsconfig.json
├── .env.example
├── .gitignore
└── README.md

Install dependencies and verify it works locally:

cd my-mcp-server
npm install
npm run dev

You should see:

MCP Stateless HTTP Server listening on port 3000

Your server is running at http://localhost:3000/mcp. Stop it with Ctrl+C. We're ready to deploy.

Want to understand the scaffolded code in detail? See our Create Your First MCP Server guide.

The Dockerfile

The scaffold includes a production-ready Dockerfile. Here's what it does:

# Multi-stage build for production
FROM node:20-alpine AS builder

WORKDIR /app

# Copy package files
COPY package.json package-lock.json ./

# Install all dependencies (including dev)
RUN npm ci

# Copy source code
COPY . .

# Build the application
RUN npm run build

# Production stage
FROM node:20-alpine AS production

WORKDIR /app

# Copy package files
COPY package.json package-lock.json ./

# Install production dependencies only
RUN npm ci --omit=dev

# Copy built application from builder stage
COPY --from=builder /app/dist ./dist

# Expose the port the app runs on
EXPOSE 3000

# Start the application
CMD ["node", "dist/index.js"]

It's a multi-stage build: the first stage compiles TypeScript, the second stage copies only the compiled output and dependencies. This keeps the final image small.

The important part: it exposes port 3000, which matches the --port 3000 flag we'll use when deploying. Cloud Build will use this Dockerfile automatically. You don't need Docker installed on your machine.

Set Up the gcloud CLI

Install gcloud CLI

Windows (via winget):

winget install Google.CloudSDK

Or download the installer.

macOS (via Homebrew):

brew install --cask google-cloud-sdk

Linux:

curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-x86_64.tar.gz
tar -xf google-cloud-cli-linux-x86_64.tar.gz
./google-cloud-sdk/install.sh

After installing, restart your terminal and authenticate:

gcloud init
gcloud auth login

Enable Billing

Cloud Run requires a billing account, even for the free tier. You won't be charged if you stay within the free limits.

Option 1: Via the console

Go to Google Cloud Billing
Click Link a billing account (or Create account if you don't have one)
Add a payment method
Select your project and link it to the billing account

Option 2: Via CLI (if you already have a billing account):

gcloud billing accounts list
gcloud billing projects link YOUR_PROJECT_ID --billing-account=YOUR_BILLING_ACCOUNT_ID

Deploy to Cloud Run

Create a New Project

We recommend creating a dedicated project for this tutorial. This keeps your demo isolated from existing resources, so cleanup commands won't accidentally affect your other projects or container images.

gcloud projects create my-mcp-project --name="My MCP Server"
gcloud config set project my-mcp-project

Project IDs must be globally unique. If my-mcp-project is taken, choose something else.

Enable Required APIs

gcloud services enable run.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com

This enables three services:

Cloud Run: hosts your container
Artifact Registry: stores your container image
Cloud Build: builds your Dockerfile remotely

Deploy from Source

Make sure you're in your project directory (my-mcp-server/), then run:

gcloud run deploy my-mcp-server \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --port 3000

Here's what each flag does:

--source .: sends your source code to Cloud Build, which builds the container using your Dockerfile
--region us-central1: deploys to a US region (or choose another region closer to you)
--allow-unauthenticated: makes your /mcp endpoint publicly accessible
--port 3000: tells Cloud Run which port your container listens on

The first deploy takes a couple of minutes as Cloud Build pulls the base image and builds your container. Subsequent deploys are faster thanks to layer caching.

Get Your Service URL

gcloud run services describe my-mcp-server --region us-central1 --format='value(status.url)'

This outputs something like:

https://my-mcp-server-abc123xyz.us-central1.run.app

Your MCP endpoint is now live at https://<service-url>/mcp.

Troubleshooting: Invalid Host Error

If you get an error like "Invalid Host: my-mcp-server-abc123xyz.us-central1.run.app", it means the server is validating the Host header and rejecting the Cloud Run domain.

Fix it by setting the ALLOWED_HOSTS environment variable:

gcloud run services update my-mcp-server \
  --region us-central1 \
  --set-env-vars ALLOWED_HOSTS=my-mcp-server-abc123xyz.us-central1.run.app

Replace the domain with your actual service URL (without https://).

Test Your Deployed Server

Let's verify everything works. Open a terminal and run:

npx @modelcontextprotocol/inspector

Once the inspector opens in your browser:

Change the transport type to Streamable HTTP
Enter your Cloud Run URL: https://<service-url>/mcp
Click Connect

You should see your server's tools listed. Click on any tool, fill in the parameters, and run it.

That's it. Your MCP server is live on the internet, accessible from any MCP-compatible client, anywhere.

Cleanup

If you want to remove the deployed resources:

# Delete the Cloud Run service
gcloud run services delete my-mcp-server --region us-central1

# Delete the container image from Artifact Registry
gcloud artifacts docker images list us-central1-docker.pkg.dev/my-mcp-project --format='value(IMAGE)' | xargs -I {} gcloud artifacts docker images delete {} --quiet

# Optionally delete the entire project (removes everything)
gcloud projects delete my-mcp-project

Note: Cloud Build stores your container image in Artifact Registry, which charges for storage after the first 500MB free. Deleting the project removes everything, but if you're keeping the project, clean up the images separately.

If you're staying within the free tier, there's no urgency to clean up. But it's good practice to remove resources you no longer need.

What's Next?

Now that your server is deployed, here are some ideas:

Add authentication: secure your deployed server with OAuth using our OAuth for MCP Servers guide.

Build real tools: replace the placeholder tools with your own by following our first MCP server guide.

Try FastMCP: build with a different framework using our FastMCP guide.

Connect your IDE: point your VS Code or Cursor MCP configuration at your Cloud Run URL instead of localhost.

Set up a custom domain: configure a custom domain in Cloud Run for a cleaner URL.

What About Stdio Servers?

Everything in this guide applies to Streamable HTTP servers, the transport designed for cloud deployment. But not all MCP servers use HTTP.

Stdio servers communicate via stdin/stdout and run as local subprocesses. They can't be deployed as web services. Instead, they're distributed so clients can run them locally: via npm (npx your-server), PyPI (uvx your-server), or Docker Hub (pull and run via Docker).

We'll cover stdio distribution in detail in a future article. Stay tuned.

Conclusion

You just went from a scaffolded project to a live, publicly accessible MCP server, in minutes, for free. No Docker installed locally, no infrastructure to manage, just a single gcloud run deploy --source . command.

With Cloud Run, your MCP server is always available, scales automatically, and costs nothing while idle. That's a pretty good deal for getting your AI tools off localhost and into the real world.

If you found create-mcp-server useful, consider giving it a star on GitHub and sharing it with others who are building MCP servers. It helps the project grow and helps more developers get started quickly.

Enjoying content like this? Sign up for Agent Briefings, where I share insights and news on building and scaling MCP Servers and AI agents.

Resources

create-mcp-server (GitHub): the CLI tool used in this guide
Google Cloud Run Documentation: official Cloud Run docs
Google Cloud Free Tier: free tier details and limits
MCP Inspector (GitHub): testing and debugging tool for MCP servers
MCP Documentation: official protocol specification
gcloud CLI Reference: CLI documentation

Lessons from OpenClaw's Architecture for Agent Builders

Ali Ibrahim — Thu, 19 Feb 2026 10:51:26 +0000

Introduction

OpenClaw has over 200,000 GitHub stars. It is one of the fastest-growing open-source projects in history. Lex Fridman discussed it on his podcast. Andrej Karpathy called one of its side projects "the most incredible sci-fi takeoff-adjacent thing" he has seen recently.

Most of the coverage has been surface-level: "look, an AI that controls your computer." But if you are building agents, the interesting question is not what OpenClaw does — it is how the architecture enables it.

OpenClaw solves a problem most agent frameworks ignore: running a persistent, multi-channel AI agent on your own hardware that does not break under real-world usage. The engineering decisions behind that are worth studying.

What you'll learn:

The 4-layer gateway architecture and why a single process matters
The Lane Queue system, the core reliability pattern most agents lack
Skills-as-markdown: why prompt engineering beat code for extensibility
Human-readable memory you can open in a text editor
Security lessons from CVEs and supply chain attacks
10 concrete patterns to adopt in your own agent systems

Why OpenClaw Matters for Builders

OpenClaw was created by Peter Steinberger, an Austrian software engineer known for building developer tools in the iOS/macOS ecosystem. The project started in November 2025 as a personal WhatsApp relay script called Clawdbot. After a trademark dispute with Anthropic, it became Moltbot, then settled on OpenClaw three days later.

Three factors drove the viral growth:

Local-first in the age of cloud lock-in. Your data, your hardware, no vendor dependency.
It actually works across platforms. WhatsApp, Telegram, Discord, iMessage, Slack, Signal, and more from a single agent.
Self-modifying skills. The agent can write and deploy its own new capabilities mid-conversation.

But the insight that matters most for builders: OpenClaw is not a framework. It is a gateway — a single runtime that sits between your AI model and the outside world. That architectural choice shaped every other decision in the project.

Let's walk through the architecture layer by layer.

The 4-Layer Architecture

OpenClaw's architecture breaks down into four distinct layers, each with a clear responsibility:

OpenClaw's 4-layer architecture: Gateway, Integration, Execution, and Intelligence.

Layer	Responsibility	Key Pattern
Gateway	Connection management, routing, auth	Single-process multiplexing
Execution	Task ordering, concurrency control	Per-session serial queues (Lane Queue)
Integration	Platform normalization	Channel adapters
Intelligence	Agent behavior, knowledge, proactivity	Skills + Memory + Heartbeat

What Runs the Agent Itself?

A notable architectural decision: OpenClaw does not implement its own agent runtime. The core agent loop — tool calling, context management, LLM interaction — is handled by the Pi agent framework (@mariozechner/pi-agent-core, pi-ai, pi-coding-agent). OpenClaw builds the gateway, orchestration, and integration layers on top of Pi.

This separation is telling. It reinforces the project's core thesis: the hard problem in personal AI agents is not the agent loop itself, but everything around it. Channel normalization, session management, memory persistence, skill extensibility, and security are where the complexity lives. Pi handles the "think and act" cycle. OpenClaw handles the "connect, queue, remember, and extend" layers.

OpenClaw also implements the Agent Client Protocol (ACP) via @agentclientprotocol/sdk, a standardized protocol for agent-to-editor communication. This bridges the Gateway to tools like code editors, mapping ACP sessions to Gateway session keys and translating between protocol-native commands (prompt → chat.send, cancel → chat.abort).

The Gateway Layer

Everything routes through a single Node.js process — the Gateway. It runs locally on port 18789 and handles WebSocket control messages, HTTP APIs (OpenAI-compatible), and a browser-based Control UI from a single multiplexed port.

This is a deliberate trade-off. A single process means no inter-process communication overhead, simple deployment (one npm i -g openclaw command), and straightforward debugging. It also means no horizontal scaling, but OpenClaw targets personal and small-team use, where operational simplicity matters more than throughput.

The Gateway enforces authentication by default. Non-loopback binding without a token is refused. The WebSocket protocol follows a strict handshake: the client sends a connect frame, and the Gateway responds with a hello-ok snapshot containing presence, health, state, uptime, and rate limits.

Note: This single-process design is a conscious trade-off. If you need horizontal scaling across many users, you need a different architecture. OpenClaw optimizes for the "personal AI assistant" use case where one Gateway serves one person (or a small team).

The Intelligence Layer

The top layer is where agent behavior lives: skills, memory, the heartbeat daemon, and multi-agent routing. We will cover each of these in dedicated sections below.

The Lane Queue: OpenClaw's Core Innovation

If you take one pattern from this article, make it this one.

The Problem

Most agent systems let multiple requests execute concurrently against the same session state. A user sends three messages in quick succession. The agent starts processing all three in parallel. Now you have three tool calls potentially writing to the same file, three API requests with contradictory assumptions, and an interleaved log that is impossible to debug.

Race conditions in agent systems are not edge cases — they are the default failure mode when you accept concurrent input without explicit ordering.

The Solution: Default Serial, Explicit Parallel

OpenClaw's Lane Queue enforces a simple rule: every session gets its own queue, and tasks within a queue execute one at a time.

With the Lane Queue, messages execute serially per session, eliminating race conditions by design.

Here is the conceptual model:

type SessionKey = `${string}:${string}:${string}` // workspace:channel:userId

class LaneQueue {
  private queues = new Map<SessionKey, Task[]>()

  async enqueue(sessionKey: SessionKey, task: Task) {
    const queue = this.queues.get(sessionKey) ?? []
    this.queues.set(sessionKey, queue)
    queue.push(task)

    if (queue.length === 1) {
      // No other task running, execute immediately
      await this.process(sessionKey)
    }
    // Otherwise, this task waits its turn
  }

  private async process(sessionKey: SessionKey) {
    const queue = this.queues.get(sessionKey)!
    while (queue.length > 0) {
      const task = queue[0]
      await task.execute() // Serial: wait for completion
      queue.shift()
    }
  }
}

The key decisions:

Session keys are structured. workspace:channel:userId, not just a user ID. This prevents cross-context data leaks between the same user in different channels.
Parallelism is opt-in. Additional lanes (e.g., cron, subagent) allow background jobs to run without blocking the main session queue. But the default is serial.
Backpressure is built in. If the agent is overwhelmed, the queue grows. You can implement timeout or overflow strategies at the queue level, not scattered across individual handlers.

Why This Matters for Your Agents

Even if you are not building a multi-channel gateway, the per-session serial queue pattern prevents an entire class of bugs. If your agent can receive concurrent input — webhooks, streaming UI, multiple users — you need something like this.

The Lane Queue also makes debugging straightforward. Every action for a given session happened in order. There is no "which thread was this?" question.

Channel Abstraction: One Agent, Ten Platforms

OpenClaw supports over a dozen messaging platforms. Core channels are implemented in src/ (WhatsApp via Baileys, Telegram via grammY, Discord via @buape/carbon, Slack via @slack/bolt, iMessage, Signal), while extension channels live in the extensions/ directory as standalone packages (Matrix via @vector-im/matrix-bot-sdk, Google Chat, Microsoft Teams, LINE, Feishu/Lark, and more).

Each of these platforms has a wildly different message format, media handling, authentication model, and rate limiting strategy. OpenClaw normalizes all of this through channel adapter interfaces defined in its plugin-sdk (including ChannelMessagingAdapter, ChannelGatewayAdapter, and ChannelAuthAdapter).

Conceptually, the pattern looks like this:

// Simplified illustration of the adapter pattern (not actual OpenClaw code)
interface ChannelAdapter {
  name: string
  connect(): Promise<void>
  send(sessionKey: string, message: UnifiedMessage): Promise<void>
  onMessage(handler: (sessionKey: string, msg: UnifiedMessage) => void): void
}

interface UnifiedMessage {
  text?: string
  media?: MediaAttachment[]
  replyTo?: string
  metadata: Record<string, unknown>
}

Key design decisions:

Adapters are stateless. Connection state lives in the Gateway, not in individual adapters. This means you can restart an adapter without losing session context.
Media is normalized. Images, audio, and documents all get the same treatment regardless of source platform. The agent does not need to know whether a photo came from WhatsApp or Telegram.
Platform-specific features use a metadata bag. Reactions, threads, typing indicators, and read receipts flow through metadata. The core agent logic never touches platform-specific fields.
Fault isolation. Each adapter starts independently. If the WhatsApp connection fails, Telegram keeps running. One failing channel does not take down the Gateway.

Takeaway for builders: If your agent integrates with even two platforms, build a normalization layer early. The unified message format is the contract between your integration layer and your intelligence layer. Without it, platform-specific logic leaks into your agent's core and becomes impossible to untangle later.

Skills: Prompt Engineering as the Extension Mechanism

OpenClaw's capabilities are modular plugins called skills, but they are not what you might expect. Skills are not TypeScript modules or Python packages. They are folders containing a SKILL.md file, a markdown document with YAML frontmatter.

This is the same format we covered in our previous article on building agent skills. OpenClaw was one of the first large projects to adopt this pattern at scale.

The skills lifecycle: discovery, activation, execution, and self-authoring.

How Skills Work

On startup, the agent reads skill names and descriptions, roughly 97 characters per skill. This is the progressive disclosure pattern: keep initial context lean.
When a user request matches a skill's description, the full skill content is injected into the agent's context as markdown.
Skills can reference local files (scripts, templates, reference data).
Skills are hot-reloadable. Edit the file, and the agent picks it up on the next turn (configurable debounce of 250ms).

The Self-Writing Agent

The feature that captured the most attention: the agent can create and edit its own SKILL.md files. It observes patterns in how the user asks for things, identifies repetitive workflows, and writes a skill to handle them better next time.

The agent stores self-authored skills in the per-agent workspace (<workspace>/skills/) or the shared ~/.openclaw/skills/ directory. These skills persist across sessions and survive restarts.

ClawHub Marketplace

OpenClaw has a community skill registry called ClawHub, where users share and discover skills via CLI commands. The agent can even auto-search for and install skills at runtime based on user intent.

This extensibility is powerful, and also where the security story gets interesting (more on that later).

Why Markdown Over Code?

Approach	Skills (Markdown)	Plugins (Code)
Extension language	Natural language + YAML	TypeScript / Python
Who can author	Anyone (including the agent)	Developers only
Security surface	Low (injected as context)	High (arbitrary code execution)
Hot reload	Trivial (re-read the file)	Requires restart or dynamic import
Debuggability	Read the file, read the prompt	Stack traces, runtime errors

The markdown-first approach has a key advantage: the barrier to creating skills is effectively zero. Users who cannot write code can still teach their agent new workflows. And the agent itself can participate in the skill ecosystem.

Note: For a hands-on guide to building skills in this format, see our How to Build and Deploy an Agent Skill from Scratch.

Memory Architecture: Files You Can Read

Most agent memory lives in a vector database that humans cannot inspect, edit, or debug. When the agent remembers something wrong, you have no practical way to fix it.

OpenClaw takes a different approach. Memory is stored as flat files:

Markdown files for long-form notes and context
YAML files for structured data (user preferences, configurations)
JSONL files for conversation history (one line per message, append-only)

Everything lives under ~/.openclaw/ in a directory structure you can browse in your file manager.

Hybrid Search

Retrieval uses two complementary search strategies, both running locally in SQLite:

Vector similarity search via sqlite-vec, which finds semantically related content even when the wording differs
Keyword search via FTS5 for precise matches on exact technical terms, names, and identifiers

Hybrid search consistently outperforms either strategy alone. Vector search introduces semantic noise on precise queries. Keyword search misses paraphrased content. Combining them gives you the best of both.

Smart Sync

When the agent writes to a memory file, a file monitor automatically triggers an index update for both vector embeddings and the full-text index. New "experiences" are immediately available for the next prompt. No manual reindexing.

Why Flat Files Matter

You can git diff your agent's memory. Version control for agent state.
You can edit memory in VS Code. Wrong fact? Fix it directly.
You can back up memory with standard file system tools. No database export needed.
You can review what your agent "knows" without building a custom admin UI.

Semantic Snapshots for Browser Automation

When OpenClaw automates a browser, it does not rely on screenshots. Instead, it parses the accessibility tree, a structured text representation of the page content. This "Semantic Snapshot" approach is cheaper in tokens, faster to process, and more accurate for LLM reasoning than pixel data.

Accessibility trees give the model structured information about buttons, links, form fields, and content hierarchy. A screenshot gives it pixels. For most agent tasks, the structured data wins.

The Heartbeat: Proactive Agents

Most agents sit idle until a user sends a message. OpenClaw has a different model.

The Gateway runs as a background daemon with a configurable heartbeat interval (30 minutes by default). On each tick, the agent reads a HEARTBEAT.md checklist in the workspace:

- Check for new emails and summarize anything urgent
- Review today's calendar for upcoming meetings
- Run daily expense summary if it's after 6 PM

The agent processes each item and can send proactive messages to the user via any connected channel. If nothing requires attention, it responds with HEARTBEAT_OK and goes back to sleep.

This is a simple but powerful pattern: a cron job for your AI agent, configured in plain text. No scheduling framework, no database of recurring tasks. Just a markdown file the user can edit.

Takeaway for builders: If your agent should be proactive, implement a heartbeat. A markdown checklist is all you need to start. It is far simpler than building a full scheduling system.

Nodes: The Companion Device Model

OpenClaw "nodes" are native apps on iOS, macOS, and Android that connect to the central Gateway via WebSocket. They act as peripherals: the phone node can take photos and read notifications, while the macOS node can interact with desktop apps and record the screen.

Nodes register through a pairing protocol (node.pair.request → node.pair.approve) and expose capabilities through a standardized node.invoke interface. The model never communicates directly with nodes. It talks to the Gateway, which forwards calls to the appropriate device.

Capability	macOS	iOS	Android	Headless
WebView (canvas)	Yes	Yes	Yes	No
Camera	Yes	Yes	Yes	No
Shell commands	Yes	No	No	Yes
SMS sending	No	No	Yes	No
Screen recording	Yes	Yes	Yes	No
Location	Yes	Yes	Yes	No

Takeaway for builders: If your agent needs device-specific capabilities, a lightweight WebSocket peripheral model is cleaner than trying to run everything on the server. The key is keeping nodes dumb: they execute commands, they do not run agent logic.

Security: The Cautionary Tale

OpenClaw's architecture is innovative. Its security track record is a cautionary tale. These lessons are essential for anyone building agent systems.

CVE-2026-25253: One-Click Remote Code Execution

The most critical vulnerability, patched in v2026.1.29:

The Gateway's Control UI trusted the gatewayUrl from the query string without validation and auto-connected on load, sending the stored authentication token in the WebSocket payload. A crafted link could redirect this token to an attacker-controlled server.

The root cause was deeper: the WebSocket server did not validate the Origin header. Any website could connect to a running OpenClaw instance. With the token, an attacker could:

Connect to the victim's local Gateway
Modify configuration (disable sandbox, weaken tool policies)
Invoke privileged actions using operator.admin and operator.approvals scopes
Run arbitrary commands on the host machine — full remote code execution

Lesson for builders: If your agent exposes any network interface — HTTP, WebSocket, gRPC — origin validation and authentication are not optional. A local-first agent is only safe if the network boundary is actually enforced. In the single-process Gateway model, one WebSocket vulnerability compromises everything because there is no isolation boundary.

ClawHub Supply Chain Attacks

ClawHub, OpenClaw's skill marketplace, became a major attack vector:

Security audits found that 12-20% of uploaded skills contained malicious instructions
A campaign called ClawHavoc distributed macOS malware through skills with professional documentation and names like solana-wallet-tracker and youtube-summarize-pro
The #1 ranked community skill silently exfiltrated data and used direct prompt injection to bypass safety guidelines

The attack vector is subtle: skills are markdown injected into agent context. A malicious skill can instruct the agent to exfiltrate data, modify other skills, or execute harmful commands. This is prompt injection via the extension ecosystem.

ClawHub's publishing requirement was minimal: a 1-week-old GitHub account. No code review, no content scanning, no sandboxing.

Lesson for builders: If your agent loads third-party skills or prompts, treat them as untrusted input. "It is just markdown" does not mean "it is safe." Sandboxing, review processes, and automated content scanning are necessary for any public skill registry.

Plaintext Credential Storage

Connected account credentials (WhatsApp sessions, API keys for Anthropic/OpenAI, Telegram bot tokens, Discord OAuth tokens) are stored as plaintext files under ~/.openclaw/. Known malware families are already building capabilities to harvest these file structures.

Lesson for builders: Use your platform's secret storage (macOS Keychain, Windows Credential Manager, Linux secret-service). Never store credentials in plaintext, even for local-first applications.

Summary

Vulnerability	Root Cause	Lesson
CVE-2026-25253 (RCE)	Missing WebSocket origin validation	Always authenticate network interfaces
ClawHub malicious skills	No skill content scanning	Treat third-party prompts as untrusted input
Plaintext credentials	No OS secret store integration	Use platform-native credential storage

Note: These issues do not diminish OpenClaw's architectural innovations. They highlight that security for AI agents requires the same rigor as any networked application, and that agent-specific attack vectors (prompt injection via skills) require new defensive patterns.

What to Take Away: A Builder's Checklist

Here are the concrete patterns from OpenClaw's architecture worth adopting in your own agent systems:

Per-session serial queues. Default to serial execution within a session. Opt into parallelism only when provably safe. This prevents an entire class of race condition bugs.
Structured session keys. Scope isolation with workspace:channel:userId, not just a user ID. This prevents cross-context data leaks.
Channel adapter pattern. If you integrate with more than one platform, normalize messages before they reach your agent logic. Do this early.
Skills as markdown. For extensibility, markdown-first beats code-first. Lower friction, agent-authorable, hot-reloadable, debuggable.
Progressive skill disclosure. Load skill names and descriptions upfront (low tokens). Load full skill content only when activated. Keep your base context lean.
Human-readable memory. Store agent state in formats you can inspect and edit: Markdown, YAML, JSONL. The debugging advantage is worth the trade-off versus opaque vector stores.
Hybrid search. Combine vector similarity with keyword search. Use SQLite (sqlite-vec + FTS5) if you want to stay local with no external dependencies.
Accessibility trees over screenshots. For browser automation, parse the accessibility tree. It is cheaper, faster, and more accurate for LLM reasoning.
Heartbeat pattern. For proactive agents, a simple cron + checklist file is enough. You do not need a complex scheduling system.
Authenticate everything. WebSocket, HTTP, local sockets. If it accepts connections, it needs origin validation and authentication. Local-first does not mean security-optional.

Conclusion

OpenClaw is not a framework you adopt — it is an architecture you study.

The project's core insight is that a personal AI agent is fundamentally a gateway problem, not a model problem. Getting the runtime right, queuing, channel normalization, memory, extensibility — matters more than which LLM you use.

The Lane Queue and Skills system are the two patterns with the broadest applicability. If you take nothing else from this article, implement per-session serial execution and consider markdown-based extensibility for your agents.

The security story is equally important. Agent systems have a larger attack surface than traditional applications because they accept natural language input from multiple untrusted sources, including their own extension ecosystems. Build with that in mind.

Build agents that are reliable before they are clever. OpenClaw got that part right.

Enjoying content like this? Sign up for Agent Briefings, where I share insights and news on building and scaling AI agents.

Resources

OpenClaw GitHub Repository: Source code and documentation
OpenClaw Official Documentation: Architecture guides and API reference
OpenClaw Official Website: Project overview and getting started
CVE-2026-25253 Details: Full vulnerability disclosure
Agent Skills Specification: The skills format OpenClaw uses at scale

How to Build and Deploy an Agent Skill from Scratch: Build your own skills using the format OpenClaw adopted
Don't Let Your AI Agent Forget: Smarter Strategies for Summarizing Message History: Memory management patterns that complement OpenClaw's approach
Writing Effective Tools for AI Agents: Production Lessons from Anthropic: Tool design principles for the capabilities layer

How to Build and Deploy an Agent Skill from Scratch

Ali Ibrahim — Mon, 16 Feb 2026 13:00:00 +0000

Introduction

AI agents are increasingly capable, but they often lack the specialized knowledge needed for real work. Your agent might write code, but does it know your team's deployment process? It can analyze data, but does it understand your company's reporting standards?

Agent Skills solve this by packaging domain expertise, workflows, and context into portable folders that agents can discover and use on demand.

What you'll build:

In this guide, you'll create a skill that teaches AI agents how to generate beautiful financial reports with charts and insights—building on Cameron AI, the personal finance assistant from our previous articles on agent prompting and tool design.

Here is an overview of the report your agent will generate with this skill:

Example report generated by the Cameron Expense Reporter skill.

What Are Agent Skills?

Agent Skills are folders containing instructions, scripts, and resources that AI tools can discover and use. Think of them as training documents for your AI assistant, except they load automatically when relevant.

The key insight is progressive disclosure. When your agent starts, it only loads the name and description of each skill—roughly 100 tokens per skill. This means you can have dozens of skills available without bloating your context window. Your agent stays fast and focused, pulling in detailed guidance only when needed.

Skills vs MCP: Complementary, Not Competing

If you've worked with MCP servers, you might wonder how skills fit in. Here's the distinction:

Aspect	Agent Skills	MCP Servers
Purpose	Teach workflows and knowledge	Provide tools and capabilities
Format	Single SKILL.md file	Server code (TypeScript, Python)
Example	"How to write agent prompts"	"Fetch URL", "Query database"

Skills provide the knowledge; MCP provides the capabilities. A skill might instruct an agent to "fetch the API documentation and analyze it", while an MCP server provides the actual fetch tool.

For a deeper dive, see the official Agent Skills specification.

Understanding SKILL.md Format

Every skill is a folder containing a SKILL.md file. This file has two parts: YAML frontmatter and markdown instructions.

Image credit: Anthropic

Required Fields

Field	Max Length	Description
`name`	64 chars	Lowercase letters, numbers, and hyphens only
`description`	1024 chars	When and why to use this skill

The description is crucial, it's what the AI uses to decide when to activate your skill. Include specific keywords that match how users naturally ask for help.

Note: The specification supports additional optional fields (license, compatibility, allowed-tools, etc.). See the official documentation for the complete list.

Building the Cameron Expense Reporter Skill

Let's build a skill for Cameron AI, a personal finance assistant that helps users manage budgets and track expenses.

For simplicity, we'll suppose that Cameron has file system access via MCP and can execute JavaScript in a sandboxed environment—the infrastructure needed to discover and run skills.

The skill we're building will teach Cameron how to transform raw expense data into professional visualizations with Chart.js.

Context: If you're new to Cameron AI, check out:

The Art of Agent Prompting: How Cameron's prompts are designed
Writing Tools for AI Agents: How Cameron's cameron_get_expenses tool works

What you'll build: A complete skill with:

6-step visualization workflow (understand request → gather data → format → generate chart → add insights → compose report)
Helper scripts for Chart.js configuration and data formatting
Reference guides for chart type selection
HTML template for professional reports

Full implementation: The complete skill is available on GitHub. We'll show function signatures and key patterns here.

Step 1: Create the Skill Directory

Create a folder structure for your skill:

mkdir -p my-skills/cameron-expense-reporter
cd my-skills/cameron-expense-reporter

# Create subdirectories for supporting files
mkdir -p scripts references assets

This skill will use:

scripts/: Reusable JavaScript utilities for charts and data formatting
references/: Decision guides and complete examples
assets/: HTML templates for professional output

Step 2: Write the Frontmatter

Create SKILL.md with frontmatter that clearly describes when to activate this skill:

---
name: cameron-expense-reporter
description: Generate financial reports with charts using Chart.js. Use when users ask to visualize spending, show trends, create expense charts, analyze spending patterns, compare categories, track budget progress, or generate financial reports. Handles chart type selection (bar/line/pie), data formatting (currency, dates, aggregation), Chart.js configuration, and insight generation. Works with expense data from tools like cameron_get_expenses or similar financial data sources.
---

Key decisions:

name: Scoped to Cameron's domain with clear purpose (we can also just use expense-reporter)
description: Includes natural trigger phrases users would say ("visualize spending", "show trends", "expense charts")

The description is critical, it determines when the AI loads this skill. Include synonyms and common phrasings.

Step 3: Define the Workflow

After frontmatter, add the skill title and a 6-step workflow:

# Cameron Expense Reporter

Generate beautiful, insightful financial reports with charts and written analysis.

## Workflow

### Step 1: Understand the Request

Identify the user's intent to select the appropriate visualization:

- Category comparison → Bar chart
- Time-series trends → Line chart
- Distribution/proportions → Pie chart
- Budget tracking → Line chart with budget reference line

### Step 2: Gather Expense Data

Use the `cameron_get_expenses` tool to retrieve relevant data...

### Step 3: Prepare and Format Data

Use helper scripts for data transformation...

### Step 4: Generate Chart Configuration

Use helper scripts to create Chart.js configurations...

### Step 5: Generate Insights

Provide written analysis alongside the chart...

### Step 6: Compose the Report

Generate HTML, markdown, or inline visualization...

Why 6 steps: Each represents a distinct decision point in the visualization workflow. This guides the AI through: intent recognition → data retrieval → transformation → rendering → analysis → output.

Step 4: Add Supporting Scripts

For complex logic, extract reusable functions into scripts. Create two JavaScript utilities:

scripts/format_financial_data.js — Data transformation:

/**
 * Aggregate expenses by category
 */
function aggregateByCategory(expenses) {
  return expenses.reduce((acc, expense) => {
    const category = expense.category || 'Other'
    acc[category] = (acc[category] || 0) + expense.amount
    return acc
  }, {})
}

/**
 * Prepare expense data for visualization
 */
function prepareChartData(expenses, aggregationType = 'category', sortByValue = true) {
  let aggregated

  switch (aggregationType) {
    case 'category':
      aggregated = aggregateByCategory(expenses)
      break
    case 'month':
      aggregated = aggregateByMonth(expenses)
      break
    case 'week':
      aggregated = aggregateByWeek(expenses)
      break
  }

  if (sortByValue && aggregationType === 'category') {
    aggregated = sortByAmount(aggregated)
  }

  return toChartFormat(aggregated)
}

// Also includes: aggregateByMonth, aggregateByWeek, formatCurrency,
// calculatePercentageChange, formatDateRange, toChartFormat, sortByAmount

scripts/generate_chart_config.js — Chart.js configuration:

/**
 * Generate a bar chart configuration for categorical spending data
 */
function generateBarChart({ title, labels, data, currency = '$' }) {
  return {
    type: 'bar',
    data: {
      labels: labels,
      datasets: [
        {
          label: 'Spending',
          data: data,
          backgroundColor: 'rgba(59, 130, 246, 0.8)',
          borderColor: 'rgba(59, 130, 246, 1)',
          borderWidth: 1,
        },
      ],
    },
    options: {
      responsive: true,
      maintainAspectRatio: false,
      plugins: {
        title: { display: true, text: title, font: { size: 16, weight: 'bold' } },
        tooltip: {
          callbacks: {
            label: function (context) {
              return currency + context.parsed.y.toFixed(2)
            },
          },
        },
      },
      scales: {
        y: {
          beginAtZero: true,
          ticks: { callback: (value) => currency + value.toFixed(0) },
        },
      },
    },
  }
}

// Also includes: generateLineChart, generatePieChart

Why scripts: Instead of inlining complex logic in SKILL.md, extract to reusable functions the AI can read and execute.

Full implementations: See the complete skill on GitHub for all utility functions.

Step 5: Add Reference Guides

For decision logic, use reference documents the AI loads on-demand:

references/chart-types-guide.md — Chart selection decision tree:

## Decision Tree

### Categorical Comparison ("Which category did I spend most on?")

**Use: Bar Chart**

Best for:

- Comparing spending across categories
- Showing top spending categories

Example queries:

- "What are my biggest expenses?"
- "Show spending by category"

### Time-Series Trends ("How is my spending changing?")

**Use: Line Chart**

Best for:

- Showing spending trends over weeks/months
- Comparing to budget over time

Example queries:

- "Show my spending trends over the year"
- "How has my spending changed?"

### Distribution/Proportions ("Where does my money go?")

**Use: Pie Chart**

Best for:

- Showing percentage breakdown
- Understanding spending distribution

Example queries:

- "Where does my money go?"
- "What percentage do I spend on dining?"

Why references: Separates decision-making guidance from the main workflow. The SKILL.md references this guide: "For chart selection, see [references/chart-types-guide.md]".

The skill also includes:

references/chartjs-examples.md: Complete HTML examples for each chart type
assets/report-template.html: Professional HTML template with placeholders

Step 6: Reference Supporting Files in SKILL.md

In your workflow, tell the AI when to use these resources:

### Step 1: Understand the Request

Identify the user's intent to select the appropriate visualization.

For detailed chart selection guidance, see [references/chart-types-guide.md](references/chart-types-guide.md).

### Step 2: Gather Expense Data

Use the `cameron_get_expenses` tool (or equivalent) to retrieve relevant data:

### Step 3: Prepare and Format Data

**Load the formatting utilities:**

<!-- Read and use scripts/format_financial_data.js -->

### Step 4: Generate Chart Configuration

**Load the chart generator:**

<!-- Read and use scripts/generate_chart_config.js -->

Progressive disclosure: Reference files are loaded on-demand by the AI when needed. You don't inline everything in SKILL.md.

Step 7: Add Best Practices to SKILL.md

Include guidance on edge cases and performance:

## Best Practices

**Data preparation:**

- Always validate date ranges before querying
- Handle empty results gracefully
- Round currency to 2 decimal places for display

**Chart configuration:**

- Use consistent color scheme (blue primary, red for warnings)
- Set responsive: true for all charts
- Format currency in tooltips and axis ticks

**Insight generation:**

- Lead with the most important finding
- Use concrete numbers, not vague language ("Dining increased 15%" not "You spent more on dining")
- Provide context (percentages, comparisons)

**Performance:**

- For large datasets (>1000 expenses), aggregate before visualizing
- Use `response_format: 'concise'` when fetching chart data

Step 8: Validate the Complete Skill

Verify your skill has all components:

cameron-expense-reporter/
├── SKILL.md                          ✓ Main instructions with 6-step workflow
├── scripts/
│   ├── generate_chart_config.js      ✓ Bar, line, pie chart generators
│   └── format_financial_data.js      ✓ Aggregation and formatting utilities
├── references/
│   ├── chart-types-guide.md          ✓ Chart selection decision tree
│   └── chartjs-examples.md           ✓ Complete working examples
└── assets/
    └── report-template.html          ✓ HTML template for reports

Validation checklist:

[ ] SKILL.md has frontmatter with clear trigger phrases
[ ] Workflow is step-by-step and actionable
[ ] Supporting scripts have clear function signatures
[ ] References are linked from main SKILL.md with relative paths
[ ] All examples use consistent patterns (Chart.js v4, Tailwind colors)

Get the complete skill: GitHub repository

Testing Your Skill

Now let's install and test the skill.

Install in Claude

The quickest way to test is with Claude.ai or Claude Desktop:

Note: If you are using the final Github repo skill, make sure to remove the expenses.csv file from the root of the skill folder before zipping and uploading to Claude.

Zip your skill folder: zip -r cameron-expense-reporter.zip cameron-expense-reporter/
Go to Settings > Capabilities and ensure "Code execution and file creation" is enabled
Scroll to the Skills section and click Upload skill
Upload your ZIP file

Upload your skill in Claude's settings.

For details, see Using Skills in Claude.

Other tools: You're not limited to Claude, any skills-compatible agent works. For example, in Cursor, place your skill folder in .cursor/skills/. You can also use skills.sh to install skills across tools with a single command: npx skills add <owner/repo>.

Test with Sample Data

Download the sample expenses CSV and try this prompt:

Here are my expenses [attach the CSV file]. Can you create a report using the cameron-expense-reporter skill?

Expected behavior:

Claude generates a report with a bar chart comparing spending.

Claude activates the cameron-expense-reporter skill
Reads the CSV data
Selects an appropriate chart type (bar chart for category comparison)
Generates a Chart.js visualization with formatted data
Provides written insights about spending patterns
Outputs a complete HTML report

Claude generates a Pie chart showing spending distribution.

Best Practices

Now that you've built your first skill, here are some tips for creating effective skills:

Keep it focused. A skill should do one thing well. If your SKILL.md exceeds 500 lines, consider splitting into multiple skills or using supporting files.

Description keywords matter. The description field determines when the AI activates your skill. Include synonyms and common phrasings for your use case.

Use supporting files strategically. Complex skills benefit from:

scripts/: Reusable code the AI can execute (JavaScript, Python, shell scripts)
references/: Decision trees, documentation, examples (loaded on-demand)
assets/: Templates, images, static files (used in output, not loaded into context)

Show function signatures, not full implementations. In SKILL.md, include:

// Good: Clear signature with purpose
function aggregateByCategory(expenses) { ... }

// Avoid: Inline implementation
// Keep actual logic in scripts/ directory

Balance brevity with completeness. The cameron-expense-reporter SKILL.md is ~290 lines:

~100 lines: Workflow steps
~100 lines: Best practices and common patterns
~90 lines: Quick references and troubleshooting

Test with real scenarios. Run your skill against actual tasks you face. Adjust the description and instructions based on what works.

Using the Skill Creator

We built the skill manually to understand each component, but you don't have to. Anthropic provides a skill-creator skill that can generate or iterate on skills for you, just describe what you want and let the AI handle the structure and formatting.

Beyond the Tutorial

The skill we built here is for learning purposes. Before shipping a skill to production or sharing it with other users, there are additional concerns to consider,especially if you're building custom agents.

Evaluation: Test your skill across diverse prompts to see how reliably the agent activates it, follows the workflow, and produces correct output. A single successful test isn't enough, edge cases and ambiguous requests will reveal gaps in your instructions.

Context management: Monitor how your agent's context grows when a skill is active. Loading full instructions plus reference files plus scripts can consume significant tokens. If your agent uses multiple skills in one session, context pressure becomes a real concern.

Infrastructure (custom agents): Coding tools like Cursor and Claude handle skill discovery and code execution out of the box. For custom agents, you may need to evaluate whether your MCP file server and sandbox are robust enough—particularly around file access permissions, execution timeouts, and error handling when scripts fail.

Conclusion

You've just created a sophisticated skill that transforms Cameron AI into a financial visualization expert. The SKILL.md file, along with its supporting scripts, reference guides, and templates—works across Cursor, Claude Code, and any custom agent with the right infrastructure.

This is the power of open standards: write once, use everywhere, whether in coding assistants or custom agents you build.

The skill you built demonstrates key patterns for production-ready agent skills:

Progressive disclosure: Only load detailed references when needed
Reusable scripts: Extract complex logic into executable functions
Decision trees: Reference guides for consistent choices
Professional output: Templates for polished deliverables

What workflow does your agent repeat most often? That's your next skill.

Enjoying content like this? Sign up for Agent Briefings, where I share insights and news on building and scaling AI agents.

Resources

Agent Skills Specification — Official open standard
Example Skills — Official skill examples
Vercel Skills — Registry of popular skills

The Art of Agent Prompting: Anthropic's Playbook — Prompt design patterns behind Cameron AI
Writing Tools for AI Agents — How to design effective tools like cameron_get_expenses
Create Your First MCP Server in 5 Minutes — Add tool capabilities to complement your skills

Create Your First MCP Server in 5 Minutes with create-mcp-server

Ali Ibrahim — Sun, 11 Jan 2026 18:41:31 +0000

Introduction

You've seen AI assistants do impressive things: answer questions, write code, explain concepts. But have you noticed their limitation? They can't actually do anything in the real world. They can't fetch live data, access your APIs, or interact with external systems.

That's where MCP comes in.

In this guide, you'll build a Fetch MCP Server, a tool that gives AI assistants (LLMs) the ability to fetch web pages and read their content. By the end, you'll have a production-ready server running locally, ready to connect to VS Code, Cursor, or any MCP-compatible client.

What you'll learn:

What MCP is and why it matters
How to scaffold an MCP server in seconds with create-mcp-server
How to implement a real-world tool (fetching URLs)
How to test your server

Prerequisites:

Node.js 20 or later
Basic TypeScript familiarity

Let's build something useful.

What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI Models (LLMs) discover and use external tools. Think of it as USB for AI: a universal connector that lets AI models plug into any tool or service you create.

The Problem

AI Models (LLMs) are powerful but isolated. They're trained on static data and can't access:

Real-time information from the web
Your company's internal APIs
Databases, file systems, or external services

Every time you need the AI to interact with the outside world, you're stuck copying and pasting data manually.

The Solution

MCP provides a standardized way for AI Models (LLMs) to:

Discover what tools are available
Understand how to use them (parameters, descriptions)
Execute them safely with user oversight

Three Core Concepts

MCP servers expose three types of capabilities:

Concept	Description	Example
Tools	Actions the AI can perform	Fetch a URL, send an email, query a database
Resources	Data the AI can read	Files, database records, API responses
Prompts	Pre-defined templates for common tasks	"Summarize this webpage"

For this tutorial, we'll focus on Tools, specifically a fetch tool that retrieves web content.

Industry Adoption

MCP isn't just a side project. Originally created by Anthropic, the protocol has been donated to the Agentic AI Foundation — a collaborative effort founded by Anthropic, Google, OpenAI, and others. With support from major players including Docker and Cloudflare, MCP is becoming the standard way AI Models interact with external systems.

For the complete specification, see the official MCP documentation.

MCP Transports: How Clients Talk to Servers

Before we build anything, let's understand how MCP clients and servers communicate. MCP supports two transport mechanisms:

Stdio (Standard Input/Output)

The original transport method. The MCP server runs as a subprocess, and the client communicates through stdin/stdout pipes.

Pros: Simple to implement, no network configuration needed.

Cons: Server must run locally, can't be shared across machines or deployed remotely.

Streamable HTTP

The modern transport method. The MCP server runs as an HTTP service, and clients connect over the network.

Pros: Deploy anywhere, share across teams, scale horizontally, add authentication.

Cons: Slightly more complex setup, requires network configuration.

Which Should You Use?

Use Case	Recommended Transport
Local development, personal tools	Stdio
Team sharing, production deployment	Streamable HTTP
Adding OAuth/authentication	Streamable HTTP
Running in Docker/cloud	Streamable HTTP

create-mcp-server generates Streamable HTTP servers. This is the right choice for production-ready servers that can be deployed, shared, and secured.

The good news: if you understand Streamable HTTP, stdio is even simpler. The MCP SDK handles both, and your tool implementations stay exactly the same. Only the transport layer changes.

Introducing create-mcp-server

Building an MCP server from scratch means setting up Express, configuring transports, handling sessions, and wiring up the MCP protocol. That's a lot of boilerplate before you write your first tool.

create-mcp-server eliminates that friction. It's a CLI tool that scaffolds production-ready MCP servers in seconds:

npx @agentailor/create-mcp-server

The CLI asks a few questions and generates a complete TypeScript project with everything configured.

Template Options

Feature	Stateless	Stateful
Session management	—	Yes
SSE support	—	Yes
OAuth option	—	Yes
Endpoints	POST /mcp	POST, GET, DELETE /mcp

Stateless: Each request is independent. Simple, but no session persistence.

Stateful: Sessions are maintained across requests. Supports Server-Sent Events for streaming. This is what most production servers need.

For this tutorial, we'll use the Stateful template (without OAuth).

Note: If you're following this tutorial in the future and the CLI prompts you to choose a framework, select Official SDK to match this guide.

Setting Up Your Project

Let's scaffold your MCP server. Run the CLI:

npx @agentailor/create-mcp-server@0.2.1 # specify this version for consistency

When prompted, enter:

Project name: fetch-mcp-server
Package manager: npm (or your preference)
Template type: Stateful
Enable OAuth authentication?: No
Initialize git repository?: Your choice

The CLI generates this structure:

fetch-mcp-server/
├── src/
│   ├── server.ts     # MCP server (tools, prompts, resources)
│   └── index.ts      # Express app and HTTP transport
├── package.json
├── tsconfig.json
├── .env.example
├── .gitignore
└── README.md

Navigate to the project and install dependencies:

cd fetch-mcp-server
npm install

Your server is ready to run, but it only has placeholder tools. Let's look at the generated code before adding our own.

Understanding the Scaffolded Code

The CLI generates two key files. Let's understand what each does.

src/index.ts — The HTTP Transport

This file handles all the networking:

import { type Request, type Response } from 'express'
import { randomUUID } from 'node:crypto'
import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js'
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js'
import { getServer } from './server.js'

const app = createMcpExpressApp()

// Map to store transports by session ID
const transports: { [sessionId: string]: StreamableHTTPServerTransport } = {}

// ... Express routes for POST, GET, DELETE /mcp

What it does:

Creates an Express app with MCP middleware
Manages sessions using unique IDs
Handles three endpoints:
- POST /mcp: Main endpoint for tool calls and messages
- GET /mcp: Server-Sent Events for streaming
- DELETE /mcp: Session cleanup

You don't need to modify this file. The transport layer is complete, just focus on server.ts.

src/server.ts — Your MCP Server

This is where the magic happens:

import type {
  CallToolResult,
  GetPromptResult,
  ReadResourceResult,
} from '@modelcontextprotocol/sdk/types.js'
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { z } from 'zod'

export function getServer() {
  const server = new McpServer(
    {
      name: 'my-mcp-server',
      version: '1.0.0',
    },
    { capabilities: { logging: {} } }
  )

  // Register tools, prompts, and resources here

  return server
}

The scaffolded version includes example implementations. We'll replace them with our fetch tool.

Building the Fetch Tool

Now for the core of our server: a tool that fetches URLs and converts HTML to readable markdown.

Install the HTML-to-Markdown Library

We need one additional dependency to convert HTML to markdown:

npm install node-html-markdown

Implement the Fetch Tool

Replace the contents of src/server.ts with:

import type { CallToolResult, GetPromptResult } from '@modelcontextprotocol/sdk/types.js'
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { z } from 'zod'
import { NodeHtmlMarkdown } from 'node-html-markdown'

// User agent for HTTP requests
const DEFAULT_USER_AGENT = 'FetchMCPServer/1.0 (+https://github.com/agentailor/fetch-mcp-server)'

export function getServer() {
  const server = new McpServer(
    {
      name: 'fetch-mcp-server',
      version: '1.0.0',
    },
    { capabilities: { logging: {} } }
  )

  // Register the fetch tool
  server.registerTool(
    'fetch',
    {
      description: `Fetches a URL from the internet and extracts its contents as markdown.

Use this tool when you need to:
- Read documentation or articles from the web
- Get current information from websites
- Access publicly available web content

The HTML content is automatically converted to clean markdown for easier reading.`,
      inputSchema: {
        url: z.url().describe('The URL to fetch. Must be a valid HTTP or HTTPS URL.'),
        max_length: z
          .number()
          .int()
          .positive()
          .max(100000)
          .default(5000)
          .describe('Maximum number of characters to return. Defaults to 5000.'),
        start_index: z
          .number()
          .int()
          .min(0)
          .default(0)
          .describe(
            'Start content from this character index. Use for pagination when content is truncated.'
          ),
        raw: z
          .boolean()
          .default(false)
          .describe('If true, returns raw HTML instead of converting to markdown.'),
      },
    },
    async ({ url, max_length = 5000, start_index = 0, raw = false }): Promise<CallToolResult> => {
      try {
        // Fetch the URL
        const response = await fetch(url, {
          headers: {
            'User-Agent': DEFAULT_USER_AGENT,
          },
          redirect: 'follow',
        })

        if (!response.ok) {
          return {
            content: [
              {
                type: 'text',
                text: `Failed to fetch ${url}: HTTP ${response.status} ${response.statusText}`,
              },
            ],
            isError: true,
          }
        }

        const contentType = response.headers.get('content-type') || ''
        const html = await response.text()

        // Check if the content is HTML
        const isHtml =
          contentType.includes('text/html') ||
          html.trim().toLowerCase().startsWith('<!doctype') ||
          html.trim().toLowerCase().startsWith('<html')

        let content: string
        let prefix = ''

        if (isHtml && !raw) {
          // Convert HTML to markdown
          content = NodeHtmlMarkdown.translate(html)
        } else {
          content = html
          if (!isHtml) {
            prefix = `Content-Type: ${contentType}\n\n`
          }
        }

        // Handle pagination
        const originalLength = content.length

        if (start_index >= originalLength) {
          return {
            content: [
              {
                type: 'text',
                text: `No more content available. Total length: ${originalLength} characters, requested start: ${start_index}.`,
              },
            ],
          }
        }

        // Extract the requested portion
        const truncatedContent = content.slice(start_index, start_index + max_length)
        const remaining = originalLength - (start_index + truncatedContent.length)

        let result = `${prefix}Contents of ${url}:\n\n${truncatedContent}`

        // Add pagination hint if content was truncated
        if (remaining > 0) {
          const nextIndex = start_index + truncatedContent.length
          result += `\n\n---\n[Content truncated. ${remaining} characters remaining. Use start_index=${nextIndex} to continue.]`
        }

        return {
          content: [
            {
              type: 'text',
              text: result,
            },
          ],
        }
      } catch (error) {
        const errorMessage = error instanceof Error ? error.message : String(error)
        return {
          content: [
            {
              type: 'text',
              text: `Error fetching ${url}: ${errorMessage}`,
            },
          ],
          isError: true,
        }
      }
    }
  )

  // Register a prompt for fetching URLs
  server.registerPrompt(
    'fetch',
    {
      description: 'Fetch a URL and extract its contents as markdown',
      argsSchema: {
        url: z.url().describe('URL to fetch'),
      },
    },
    async ({ url }): Promise<GetPromptResult> => {
      return {
        messages: [
          {
            role: 'user',
            content: {
              type: 'text',
              text: `Please fetch and summarize the content from: ${url}`,
            },
          },
        ],
      }
    }
  )

  return server
}

Code Breakdown

Let's understand what we built:

Tool Registration: The server.registerTool() method defines our fetch tool with:

A descriptive name and description (helps AI understand when to use it)
An input schema using Zod for validation
An async handler function that does the actual work

Input Parameters:

Parameter	Type	Default	Description
`url`	string	—	The URL to fetch (required)
`max_length`	number	5000	Max characters to return
`start_index`	number	0	Start position for pagination
`raw`	boolean	false	Skip HTML-to-markdown conversion

HTML Conversion: We use node-html-markdown to convert HTML to clean markdown. This makes web content much easier for AI to process.

Pagination: Long content is truncated with a helpful message showing how to fetch the next chunk.

Error Handling: Network errors and HTTP failures return user-friendly error messages.

Testing Your Server

Start your server:

npm run dev

You should see:

MCP Stateful HTTP Server listening on port 3000

Your server is now running at http://localhost:3000/mcp.

Using MCP Inspector

The project includes a testing tool. In a new terminal:

npm run inspect

Once the inspector opens in your browser:

Change the transport from STDIO to HTTP
Click Connect in the left sidebar

Testing the Prompt

Go to Prompts → List Prompts (you'll see the fetch prompt we created)
Click on the fetch prompt
Paste a URL in the input field

Testing the Tool

Go to Tools → List Tools
Click the fetch tool
You'll see a form with all the parameters we defined (url, max_length, start_index, raw)
Fill in the url (required) and keep the defaults for other fields
Click Run Tool

The result will display the fetched content converted to markdown:

Tip: Try fetching https://modelcontextprotocol.io/docs/getting-started/intro to see how the tool converts documentation pages to clean markdown.

Connecting to VS Code or Cursor

To use your server with VS Code or Cursor:

Your server URL: http://localhost:3000/mcp
VS Code setup: See the official VS Code MCP documentation
Cursor setup: See the official Cursor MCP documentation

Once connected, your AI assistant can use the fetch tool to read web pages directly.

What's Next?

You've built a working MCP server. Here are some ideas to extend it:

Add caching: Store fetched pages to avoid repeated requests for the same URL.

Support more content types: Handle PDFs, images, or JSON APIs.

Add rate limiting: Prevent abuse when deploying publicly.

Secure your server: Add OAuth authentication using our OAuth for MCP Servers guide.

Publish to the registry: Share your server with the community by following our publishing guide.

Deploy with Docker: See our guide on running MCP servers with Docker.

Conclusion

You've just built something that major AI platforms are adopting as a standard. In under 5 minutes, you went from zero to a production-ready MCP server that gives AI assistants the ability to fetch and read web content.

The complete code is available on GitHub: agentailor/fetch-mcp-server

Clone it, extend it, deploy it. The MCP ecosystem is growing fast, and now you're part of it.

Enjoying content like this? Sign up for Agent Briefings, where I share insights and news on building and scaling MCP Servers and AI agents.

Resources

Fetch MCP Server (GitHub) — Complete code from this tutorial
create-mcp-server (GitHub) — The CLI tool used in this guide
MCP Documentation — Official protocol specification
VS Code MCP Servers — VS Code integration guide
Cursor MCP Documentation — Cursor integration guide

Top 5 TypeScript AI Agent Frameworks You Should Know in 2026

Ali Ibrahim — Thu, 01 Jan 2026 15:00:00 +0000

In GitHub's 2025 language report, TypeScript officially surpassed Python. The race was fierce, but TypeScript won. While Python still dominates the AI agent ecosystem, JavaScript and TypeScript are the fastest-growing alternatives—and for good reason. Full-stack developers can now build AI agents without switching stacks.

If you want the full picture across all languages, check out Top 10 Most Starred AI Agent Frameworks on GitHub (2026). This article focuses on the TypeScript ecosystem.

Short on time? Get the key takeaways of this article in under 5 seconds with DocuMentor AI, my Chrome extension. No account required. Try it Here

1. Vercel AI SDK ⭐ 20,400 | 📦 2.8M downloads/week

From the creators of Next.js, the Vercel AI SDK is the most downloaded TypeScript AI framework by a massive margin. It provides streaming-first primitives for building AI-powered user interfaces, with built-in support for React Server Components and edge runtimes.

Best for: React and Next.js developers who want to add AI features to their web applications with minimal friction.

GitHub: vercel/ai

2. Mastra ⭐ 19,024 | 📦 151K downloads/week

Mastra is a TypeScript-native AI agent framework built for production. It includes assistants, RAG pipelines, and built-in observability out of the box. Unlike ports from Python, Mastra was designed from the ground up for the TypeScript ecosystem.

Best for: Teams building production-grade agent systems who need full observability and don't want to piece together multiple libraries.

GitHub: mastra-ai/mastra

3. LangChain.js ⭐ 16,600 | 📦 795K downloads/week

The JavaScript port of the most popular Python AI framework. LangChain.js brings the same modular architecture—chains, agents, tools, and memory—to the JS ecosystem. If your team already uses LangChain in Python, the API will feel familiar.

Best for: Teams already invested in the LangChain ecosystem, or developers who want access to LangChain's extensive documentation and community.

GitHub: langchain-ai/langchainjs

4. VoltAgent ⭐ 4,478 | 📦 151K downloads/week

VoltAgent is an open-source AI agent framework with LLM observability built into its core. It's a rising star in the ecosystem, offering debugging and tracing capabilities that are often afterthoughts in other frameworks.

Best for: Developers who prioritize debugging, tracing, and understanding what their agents are actually doing under the hood.

GitHub: VoltAgent/voltagent

5. LangGraph.js ⭐ 2,388 | 📦 529K downloads/week

LangGraph.js brings graph-based orchestration to AI agents. Instead of linear chains, you define your agent logic as nodes and edges—making it easier to build complex, multi-step workflows with branching, loops, and conditional logic.

Best for: Complex agent workflows that need fine-grained control over execution flow, especially multi-agent systems.

GitHub: langchain-ai/langgraphjs

Special Mentions

These frameworks are brand new but backed by major players. Watch this space.

Google ADK TypeScript ⭐ 581 | 📦 5K downloads/week — Google's agent development toolkit, released December 2025. Code-first approach with flexibility and control.
OpenAI Agents SDK TypeScript ⭐ 2,100 | 📦 128K downloads/week — Official OpenAI framework for multi-agent workflows and voice agents. Lightweight but powerful.

Key Insights

Vercel AI SDK dominates downloads — 2.8M weekly vs. the next best at 795K. The Next.js ecosystem effect is real.
LangGraph.js punches above its weight — Only 2.3K stars but 529K weekly downloads. Developers are using it, even if they're not starring it.
Stars ≠ adoption — Mastra has more stars than LangChain.js but fewer downloads. Community buzz doesn't always match production usage.
The big players just arrived — Google ADK and OpenAI SDK are brand new. Momentum over the next 6 months will tell the real story.

What to Read Next

Enjoying content like this? Sign up for Agent Briefings, where I share insights and news on building and scaling AI agents.

Star counts and npm downloads as of January 2026. Numbers change—check the repos and npm for the latest.

Top 10 Most Starred AI Agent Frameworks on GitHub (2026)

Ali Ibrahim — Wed, 31 Dec 2025 21:40:27 +0000

AI agents are reshaping how we build software. GitHub stars are a strong indicator of developer trust and community adoption. Here are the top 10 most starred AI agent frameworks heading into 2026.

Short on time? Get the key takeaways of this article in under 5 seconds with DocuMentor AI, my Chrome extension. No account required. Try it Here

1. LangChain ⭐ 122,850

langchain-ai/langchain | Python | MIT

The most popular framework for building LLM-powered applications, with extensive tooling for chains, agents, and retrieval.

2. MetaGPT ⭐ 61,919

FoundationAgents/MetaGPT | Python | MIT

A multi-agent framework that simulates a software company, with agents taking on roles like product manager, architect, and engineer.

3. AutoGen ⭐ 52,927

microsoft/autogen | Python | CC-BY-4.0

Microsoft's framework for building multi-agent conversational systems with customizable agent behaviors.

4. LlamaIndex ⭐ 46,100

run-llama/llama_index | Python | MIT

The leading framework for connecting LLMs to your data, with powerful indexing and retrieval capabilities.

5. CrewAI ⭐ 41,871

crewAIInc/crewAI | Python | MIT

Framework for orchestrating role-playing autonomous agents that collaborate to accomplish complex tasks.

6. Agno ⭐ 36,414

agno-agi/agno | Python | Apache-2.0

A multi-agent framework with a runtime and control plane for managing agent deployments at scale.

7. Haystack ⭐ 23,741

deepset-ai/haystack | Python | Apache-2.0

Production-ready AI orchestration framework focused on building customizable LLM applications and RAG pipelines.

8. Vercel AI SDK ⭐ 20,400

vercel/ai | TypeScript | Apache-2.0

The AI toolkit for TypeScript from the creators of Next.js, designed for building AI-powered web applications.

9. Open-AutoGLM ⭐ 19,800

zai-org/Open-AutoGLM | Python | Apache-2.0

An open-source phone agent model and framework for building mobile device automation agents.

10. Mastra ⭐ 19,021

mastra-ai/mastra | TypeScript | Apache-2.0

A TypeScript-native AI agent framework with built-in workflows, tools, and integrations.

Special Mentions

Stars don't tell the whole story. These frameworks have fewer stars but are gaining momentum with high download counts and modern architectures.

OpenAI Agents SDK ⭐ 18,022 — Official OpenAI framework for multi-agent workflows
Google ADK Python ⭐ 16,800 — Google's new agent development toolkit
Pydantic AI ⭐ 14,000 — The Pythonic way to build AI agents

Key Takeaways

Python dominates: 8 out of 10 top frameworks are Python-based
LangChain leads by a massive margin with 2x the stars of the runner-up
TypeScript options: Vercel AI SDK and Mastra for JS/TS developers
Watch the special mentions: Momentum matters more than legacy stars

What to Read Next

Enjoying content like this? Sign up for Agent Briefings, where I share insights and news on building and scaling AI agents.

Star counts as of January 2026. Numbers change—check the repos for the latest.

Engineering Context for Local and Cloud AI: Personas, Content Intelligence, and Zero-Prompt UX

Ali Ibrahim — Sat, 20 Dec 2025 14:55:45 +0000

In the previous article, we covered how DocuMentor AI's hybrid architecture seamlessly adapts between Chrome's local Gemini Nano and cloud AI. We built a system that automatically routes tasks based on capabilities and performance constraints.

But having a robust execution layer is only half the battle. The other half? Engineering the context that goes into those models.

This is where most AI tools fall short. They give you a powerful model and a blank text box, then expect you to figure out what to ask. It's like handing someone a professional camera and saying "take a good photo"—technically possible, but the burden is entirely on the user.

DocuMentor takes a different approach: zero-prompt UX through intelligent context engineering. Users never write prompts. They click a feature (Quick Scan, Deep Analysis, Cheat Sheet), and the extension handles the rest—assembling the right persona elements, extracting the right page sections, and shaping everything into a request the AI can't misinterpret.

This article breaks down how that works: the philosophy behind zero-prompt design, the persona system that personalizes every response, and the content intelligence layer that knows exactly what to send to the AI.

The Zero-Prompt Philosophy

Most technical documentation tools and AI-powered browsers present the same UX pattern: a blank chat input with a placeholder like "Ask me anything about this page."

This seems user-friendly on the surface, but if you don't know what you want to ask, it creates three problems:

Cognitive load - Users have to think about how to phrase their question
Intent ambiguity - Small wording changes lead to wildly different answers
Generic responses - Without context about the user, AI gives one-size-fits-all answers

I built DocuMentor to solve my own problem: I spend hours every week scanning documentation, blog posts, and API references trying to extract what I need quickly. Sometimes I want a TL;DR to decide if it's worth reading. Other times I need a cheat sheet for future reference. And sometimes I just want to know "should I care about this?"

These are specific, recurring needs. Why should I have to articulate them from scratch every time?

The solution: feature-first design. Instead of a blank chat box, DocuMentor exposes four purpose-built features:

Quick Scan - Instant insights: TL;DR, "should I read this?", related resources, page architecture
Deep Analysis - The deep dive: comprehensive overview, code patterns, video recommendations, learning resources with reasoning
Cheat Sheet - Future reference: condensed, actionable summary optimized for quick lookup
AskMe - Targeted chat: select text or images and ask specific questions

Each feature represents a pre-crafted intent. Users don't have to think about how to ask, they just pick the outcome they want. The extension takes care of the rest: crafting the prompt, selecting the right page sections, and applying the user's persona.

This isn't just about convenience. It's about eliminating ambiguity. When a user clicks "Quick Scan," there's zero room for misinterpretation. The AI knows exactly what format to return, what level of detail to provide, and what the user cares about.

Persona-Driven Personalization

After building the initial feature set, I realized something critical: none of these features should return generic answers.

A "Should I read this?" recommendation means nothing without knowing who's asking. A senior AI engineer doesn't need to read an intro to neural networks. A junior frontend developer does need to read advanced React hooks patterns. Same feature, same page, completely different answers.

That's when I introduced the persona system—a user profile that shapes every AI response:

What's in a persona:

Role - AI/ML Engineer, Frontend Developer, Backend Engineer, etc.
Seniority - Beginner, Intermediate, Senior
Skills - Programming languages, frameworks, concepts each with a proficiency level (Beginner, Intermediate, Advanced)
Learning Goals - What the user wants to master right now (e.g., "Master LangGraph for production AI agents")
Learning Preferences - Text, video, or mixed

Figure: The five components of a DocuMentor persona.

The challenge wasn't just collecting this information—it was knowing which elements matter for which features.

For example:

Learning preferences are irrelevant for cheat sheets (the user already decided they want text)
Skills and goals are critical for "Should I read this?" recommendations
Seniority affects explanation depth across all features
Role determines which code patterns to highlight in Deep Analysis

This creates a mapping problem: each feature needs a subset of the persona, not the whole thing. Sending irrelevant persona data just adds noise and wastes tokens (especially on local AI with tight context limits).

Here's where it gets interesting. Let's say you're a Junior Frontend Developer learning React, and you land on an article about advanced state management patterns. DocuMentor's "Should I read this?" feature might say:

Yes, read this. This covers useReducer and Context API patterns that will level up your React skills. It assumes familiarity with useState, which you have. The examples are practical and match your learning goal: mastering React for production apps.

Now imagine a Senior Backend Engineer who knows React but isn't focused on frontend work hits the same page:

Skip this. You already understand these patterns from your React experience. This won't advance your current goal (mastering distributed systems). If you need a refresher later, the cheat sheet feature has you covered.

Same page. Same feature. Completely different recommendations, because the persona told the AI who's asking and why they care.

This isn't just personalization for its own sake. It's about respecting the user's time. Generic AI tools waste your time by making you read irrelevant content or miss important insights. Persona-driven AI acts like a knowledgeable colleague who knows your background and priorities.

Content Intelligence: Strategic Page Decomposition

Early on, I made the naive mistake most AI developers make: I fed the entire page HTML to the model, assuming it could "figure it out."

This failed spectacularly:

Context overflow - Raw HTML easily exceeds Chrome AI's ~4K token limit
Noise drowning signal - Ads, navigation, footers, and JavaScript compete with actual content
Hallucinations - Small models like Gemini Nano get confused by irrelevant information

The first fix was obvious: content extraction. I used Mozilla's Readability library (with a custom fallback for pages where Readability fails) to extract clean, readable text from the page.

But that still wasn't enough. Even clean content presented a new problem: not every feature needs the same information.

For example:

Summaries and cheat sheets need the full article content
Video recommendations only need a summary of the page (not 10K words of content)
"Learn Resources" suggestions need page links and navigation context, not the article body

Sending everything to every feature wastes tokens, increases latency, and reduces relevance. The solution: strategic page decomposition.

DocuMentor breaks every page into purpose-driven sections:

Main content - The core article text (extracted via Readability)
Table of contents - Page structure and hierarchy
Page links - URLs embedded in the content
Code blocks - Extracted separately for pattern analysis
Breadcrumbs & navigation - Contextual metadata about where this page fits in the documentation

Each feature gets exactly what it needs:

Feature	Content Sections Used
Summary	Main content
Cheat Sheet	Main content + code blocks + page links
Video Recommendations	Summary only (not full content)
Learn Resources	Summary + page links + breadcrumbs + navigation
Code Patterns (Deep Analysis)	Code blocks + surrounding context

Figure: Page sections are strategically routed to different features based on what information is actually relevant.

Let's look at a concrete example: video recommendations.

The naive approach would send the full article content and ask the AI to find relevant YouTube videos. For a 10K-word documentation page, this would:

Burn through most of Chrome AI's token budget on a single feature
Slow down the response (the model has to process 10K words before even calling the YouTube API)
Risk quota errors on devices with lower VRAM

Instead, DocuMentor:

Generates a summary of the page (200-300 words)
Sends the summary + user persona to the AI
AI generates an optimal YouTube search query based on the topic and user's learning goals
Calls the YouTube Data API (handled by the extension, not the AI)
AI ranks the top 10 results based on relevance to the user's goals and the page summary
Returns the top 3 videos with compelling, personalized descriptions

This approach is 10x faster and uses 1/10th the tokens compared to sending full content. And because the AI only sees relevant information (summary + persona), the recommendations are more accurate.

This pattern repeats across every feature: content intelligence isn't about giving the AI more information—it's about giving it the right information.

Adaptive Prompting Across Providers

One final layer of context engineering: how you shape the request matters as much as what you send.

As covered in the previous article, DocuMentor runs on two AI providers: Chrome's local Gemini Nano and a cloud backend (Gemini 2.0 Flash). They have radically different capabilities.

For the same feature, the prompts are adapted:

Gemini Nano (local):

Simple, directive instructions
One reasoning task per prompt
Defensive output parsing (it sometimes returns malformed JSON)

Cloud models:

Richer, multi-step instructions
Tool-calling support
Reliable structured output

The persona and content sections stay the same, but the way they're framed changes based on the model's reasoning capacity.

For example, video recommendations on local AI use sequential decomposition (covered in the previous article): generate search query → call API → rank results → format output. Each step is a separate AI call.

On cloud AI, the same feature runs as a single tool-augmented call: the model generates the query, calls the YouTube tool, ranks results, and formats the output—all in one request.

Users never see this complexity. They click "Video Recommendations," and the system automatically routes to the appropriate provider and prompt strategy.

What's Next

This is just the first version of DocuMentor's context engineering system. Two areas I'm exploring for future iterations:

1. User-customizable feature prompts

Let users add personalized instructions to individual features. For example:

"In summaries, always include a brief definition of core concepts"
"For video recommendations, prioritize short tutorials under 15 minutes"
"When suggesting resources, focus on official documentation over blog posts"

This would let users fine-tune the experience without overthinking every request.

2. Dynamic personas

Right now, personas are static. But a fullstack developer might want to view a page as a frontend engineer one day and a backend engineer the next, depending on context.

Future versions could let users switch personas per page or even infer persona adjustments based on the content type (e.g., automatically apply a "security-focused" lens when reading about authentication).

The goal remains the same: personalization without overthinking. AI should adapt to you, not the other way around.

Conclusion

Building effective AI features isn't just about picking the right model or writing clever prompts. It's about engineering the context that goes into those prompts: knowing your user (persona), knowing what information matters (content intelligence), and eliminating ambiguity (zero-prompt UX).

DocuMentor's context engineering system rests on three pillars:

Zero-prompt UX - Features replace chat boxes, eliminating user guesswork
Persona-driven personalization - Every response adapts to role, skills, goals, and preferences
Content intelligence - Strategic decomposition ensures features get exactly what they need

The result: an AI tool that feels less like a chatbot and more like a knowledgeable colleague who understands what you're trying to accomplish.

If you want to see this in action, try DocuMentor AI on a technical article or documentation page. And if you find it useful, the best way to support this work is to leave a review and share it with someone who might benefit.

I'd also love to hear from you: What other aspects of building DocuMentor would you like to hear about? Drop a comment or reach out—your feedback shapes what I write next.

Engineering Context for Local and Cloud AI: Personas, Content Intelligence, and Zero-Prompt UX

Ali Ibrahim — Sat, 20 Dec 2025 14:47:30 +0000

But having a robust execution layer is only half the battle. The other half? Engineering the context that goes into those models.

The Zero-Prompt Philosophy

Most technical documentation tools and AI-powered browsers present the same UX pattern: a blank chat input with a placeholder like "Ask me anything about this page."

This seems user-friendly on the surface, but if you don't know what you want to ask, it creates three problems:

Cognitive load - Users have to think about how to phrase their question
Intent ambiguity - Small wording changes lead to wildly different answers
Generic responses - Without context about the user, AI gives one-size-fits-all answers

These are specific, recurring needs. Why should I have to articulate them from scratch every time?

The solution: feature-first design. Instead of a blank chat box, DocuMentor exposes four purpose-built features:

Quick Scan - Instant insights: TL;DR, "should I read this?", related resources, page architecture
Deep Analysis - The deep dive: comprehensive overview, code patterns, video recommendations, learning resources with reasoning
Cheat Sheet - Future reference: condensed, actionable summary optimized for quick lookup
AskMe - Targeted chat: select text or images and ask specific questions

Persona-Driven Personalization

After building the initial feature set, I realized something critical: none of these features should return generic answers.

That's when I introduced the persona system—a user profile that shapes every AI response:

What's in a persona:

Role - AI/ML Engineer, Frontend Developer, Backend Engineer, etc.
Seniority - Beginner, Intermediate, Senior
Skills - Programming languages, frameworks, concepts each with a proficiency level (Beginner, Intermediate, Advanced)
Learning Goals - What the user wants to master right now (e.g., "Master LangGraph for production AI agents")
Learning Preferences - Text, video, or mixed

Figure: The five components of a DocuMentor persona.

The challenge wasn't just collecting this information—it was knowing which elements matter for which features.

For example:

Learning preferences are irrelevant for cheat sheets (the user already decided they want text)
Skills and goals are critical for "Should I read this?" recommendations
Seniority affects explanation depth across all features
Role determines which code patterns to highlight in Deep Analysis

Yes, read this. This covers useReducer and Context API patterns that will level up your React skills. It assumes familiarity with useState, which you have. The examples are practical and match your learning goal: mastering React for production apps.

Now imagine a Senior Backend Engineer who knows React but isn't focused on frontend work hits the same page:

Skip this. You already understand these patterns from your React experience. This won't advance your current goal (mastering distributed systems). If you need a refresher later, the cheat sheet feature has you covered.

Same page. Same feature. Completely different recommendations, because the persona told the AI who's asking and why they care.

Content Intelligence: Strategic Page Decomposition

Early on, I made the naive mistake most AI developers make: I fed the entire page HTML to the model, assuming it could "figure it out."

This failed spectacularly:

Context overflow - Raw HTML easily exceeds Chrome AI's ~4K token limit
Noise drowning signal - Ads, navigation, footers, and JavaScript compete with actual content
Hallucinations - Small models like Gemini Nano get confused by irrelevant information

The first fix was obvious: content extraction. I used Mozilla's Readability library (with a custom fallback for pages where Readability fails) to extract clean, readable text from the page.

But that still wasn't enough. Even clean content presented a new problem: not every feature needs the same information.

For example:

Summaries and cheat sheets need the full article content
Video recommendations only need a summary of the page (not 10K words of content)
"Learn Resources" suggestions need page links and navigation context, not the article body

Sending everything to every feature wastes tokens, increases latency, and reduces relevance. The solution: strategic page decomposition.

DocuMentor breaks every page into purpose-driven sections:

Main content - The core article text (extracted via Readability)
Table of contents - Page structure and hierarchy
Page links - URLs embedded in the content
Code blocks - Extracted separately for pattern analysis
Breadcrumbs & navigation - Contextual metadata about where this page fits in the documentation

Each feature gets exactly what it needs:

Feature	Content Sections Used
Summary	Main content
Cheat Sheet	Main content + code blocks + page links
Video Recommendations	Summary only (not full content)
Learn Resources	Summary + page links + breadcrumbs + navigation
Code Patterns (Deep Analysis)	Code blocks + surrounding context

Figure: Page sections are strategically routed to different features based on what information is actually relevant.

Let's look at a concrete example: video recommendations.

The naive approach would send the full article content and ask the AI to find relevant YouTube videos. For a 10K-word documentation page, this would:

Burn through most of Chrome AI's token budget on a single feature
Slow down the response (the model has to process 10K words before even calling the YouTube API)
Risk quota errors on devices with lower VRAM

Instead, DocuMentor:

Generates a summary of the page (200-300 words)
Sends the summary + user persona to the AI
AI generates an optimal YouTube search query based on the topic and user's learning goals
Calls the YouTube Data API (handled by the extension, not the AI)
AI ranks the top 10 results based on relevance to the user's goals and the page summary
Returns the top 3 videos with compelling, personalized descriptions

This pattern repeats across every feature: content intelligence isn't about giving the AI more information—it's about giving it the right information.

Adaptive Prompting Across Providers

One final layer of context engineering: how you shape the request matters as much as what you send.

As covered in the previous article, DocuMentor runs on two AI providers: Chrome's local Gemini Nano and a cloud backend (Gemini 2.0 Flash). They have radically different capabilities.

For the same feature, the prompts are adapted:

Gemini Nano (local):

Simple, directive instructions
One reasoning task per prompt
Defensive output parsing (it sometimes returns malformed JSON)

Cloud models:

Richer, multi-step instructions
Tool-calling support
Reliable structured output

The persona and content sections stay the same, but the way they're framed changes based on the model's reasoning capacity.

On cloud AI, the same feature runs as a single tool-augmented call: the model generates the query, calls the YouTube tool, ranks results, and formats the output—all in one request.

Users never see this complexity. They click "Video Recommendations," and the system automatically routes to the appropriate provider and prompt strategy.

What's Next

This is just the first version of DocuMentor's context engineering system. Two areas I'm exploring for future iterations:

1. User-customizable feature prompts

Let users add personalized instructions to individual features. For example:

"In summaries, always include a brief definition of core concepts"
"For video recommendations, prioritize short tutorials under 15 minutes"
"When suggesting resources, focus on official documentation over blog posts"

This would let users fine-tune the experience without overthinking every request.

2. Dynamic personas

Right now, personas are static. But a fullstack developer might want to view a page as a frontend engineer one day and a backend engineer the next, depending on context.

The goal remains the same: personalization without overthinking. AI should adapt to you, not the other way around.

Conclusion

DocuMentor's context engineering system rests on three pillars:

Zero-prompt UX - Features replace chat boxes, eliminating user guesswork
Persona-driven personalization - Every response adapts to role, skills, goals, and preferences
Content intelligence - Strategic decomposition ensures features get exactly what they need

The result: an AI tool that feels less like a chatbot and more like a knowledgeable colleague who understands what you're trying to accomplish.

I'd also love to hear from you: What other aspects of building DocuMentor would you like to hear about? Drop a comment or reach out—your feedback shapes what I write next.

I was tired of copy-pasting to ChatGPT, so I built a Chrome extension

Ali Ibrahim — Mon, 15 Dec 2025 19:12:38 +0000

Every article I write requires hours of research. I open 10, 20, sometimes 30 browser tabs. Technical docs. Blog posts. GitHub READMEs. API references. Research papers.

Most of them? Not worth the 15 minutes I spend reading them.

But I don't know that until I'm already 10 minutes in.

So I developed a workflow: copy the article, open ChatGPT, paste, type "summarize this and give me the key points," wait for the response, read the summary, decide if it's worth a full read.

Then repeat. For every. Single. Article.

The breaking point

After the 50th time opening a new ChatGPT tab, pasting a wall of text, and typing the same prompt, I thought: "There has to be a better way."

I wasn't learning faster. I was spending more time managing my learning workflow than actually learning.

The problem wasn't ChatGPT. The problem was the context switching. Every time I wanted to understand something:

Highlight text on the page
Copy it
Open a new tab
Paste into ChatGPT
Write a prompt
Wait for the response
Switch back to the original tab
Try to remember where I was

My flow was broken. My focus was scattered. And I was tired of writing the same prompts over and over.

What I built

I built DocuMentor AI: a Chrome extension that does all of this on the page I'm already reading.

No copy-paste. No tab switching. No prompt engineering.

Just click the extension icon, and it analyzes the page instantly using Chrome's built-in AI (Gemini Nano). Everything happens locally in your browser—no uploading content to cloud services by default.

Here's what it does:

Quick Scan – "Is this worth reading?"

Click the extension. Get an instant answer to "Should I read this?" in about 5 seconds.

Summary of the main ideas
Difficulty level (beginner, intermediate, advanced)
Prerequisites you should know first
Estimated reading time

All matched to your skill level and learning goals.

No more bookmarking articles you'll never open. No more reading 10 minutes into something before realizing it's not relevant.

You decide before you invest the time.

Deep Analysis – Extract what actually matters

When you find something worth reading, run a Deep Analysis.

It extracts:

Core concepts and design decisions
Trade-offs and limitations
Code patterns, anti-patterns, and best practices from examples
Related topics you might want to review first

You're not just reading anymore. You're building a mental model of why things work the way they do.

Cheat Sheet Generator – Save the good stuff

You know that feeling when you google the same Git command for the fourth time this month?

That stops here.

One click generates a clean Markdown cheat sheet from the current page:

Key concepts and commands
Code snippets with syntax highlighting
"Gotchas" and edge cases in one place

Download it. Save it to Obsidian, Notion, your notes app, a Git repo—wherever you keep your personal knowledge base.

You own the reference. No cloud lock-in. No subscription required to access your own notes.

Ask Me – No more copy-paste

Select any text or code snippet on the page. Click "Ask Me." Get an explanation grounded in the content you're reading—without leaving the tab.

Ask things like:

"Explain this like I'm a junior developer"
"What does this code actually do?"
"When would I use this pattern?"

The answers reference the actual documentation in front of you, not generic web results.

Your questions and the page content are processed locally. Nothing leaves your browser by default.

Smart Recommendations – What to learn next

After you finish reading, DocuMentor AI suggests:

What to learn next based on the current topic
Follow-up docs and related concepts worth exploring
Videos and alternative resources when you'd rather watch than read

All personalized to your skill level and role (set once in your User Persona, applied everywhere).

Why local-first matters

Here's the thing: I care about privacy. I don't want to upload every technical article I read to a random cloud service just to get a summary.

DocuMentor AI runs on Chrome's built-in Gemini Nano model (requires Chrome 138+). That means:

AI processing happens locally in your browser
Page content never leaves your device by default
No tracking, no data uploads, no "we'll use your data to train our models"

You can optionally enable cloud sync for cross-device features, but it's off by default.

Your research workflow? Your reading history? Your learning profile? All stored on your device. You control the data.

What I learned building this

The biggest surprise? Developers hate writing prompts as much as I do.

Everyone I showed this to said the same thing: "Wait, it just knows what I want without me having to ask?"

Turns out, most people learning from technical docs want the same things:

Is this worth reading?
What are the key concepts?
Can I save this for later?
What should I learn next?

By building those workflows directly into the extension, I removed the friction of thinking about how to ask. You just click and get what you need.

The other thing I learned: local AI is fast enough. Chrome's Gemini Nano can analyze a full documentation page in seconds. No API latency. No rate limits. No "you've exceeded your quota" errors.

Try it

If you're tired of the copy-paste-to-ChatGPT workflow, give DocuMentor AI a shot.

👉 [Chrome Web Store link] (Requires Chrome 138+ for local AI)

I'd love to hear your feedback:

What doc would you scan first?
What feature would make this more useful for you?
What's missing?

Drop a comment or reach out. I'm actively working on this and want to build something that actually fits how developers learn.

Built with:

Chrome's built-in AI (Gemini Nano)
Next.js for the marketing site
TypeScript everywhere

Currently: Local AI free forever and 100% free Cloud AI during early access.

Stop fighting with prompts. Let the extension read the docs for you.

DEV Community: Ali Ibrahim

5 Agent Skills I’d install before starting any new agent project in 2026

1. prompt-engineer

2. skill-creator

3. mcp-builder

4. agentic-eval

5. openai-docs

Bonus: ai-sdk

Quick Reference

Key Takeaways

What to Read Next

Resources

Securing MCP Servers: A Practical Guide with Keycloak (using create-mcp-server)

Introduction

Understanding MCP Authorization

Why Security Matters

OAuth: The Hotel Key Card

Dynamic Client Registration (DCR)

Introducing create-mcp-server

Two Templates

Scaffolding Your Secure MCP Server

Key Files Explained

Setting Up Keycloak

Running Keycloak with Docker

Configuring Keycloak

1. Create a Realm

2. Create a Client

Environment Variables

3. Create a Test User

Connecting MCP Server to Keycloak

Testing Your Secure MCP Server

Setting Redirect URIs for VS Code and Cursor

VS Code Integration

Cursor Integration

Terminal Client Testing

Enabling Dynamic Client Registration in Keycloak

Creating the mcp:tools Scope

Running the Terminal Client

Adding Custom Tools

Using MCP Inspector

Recap

Conclusion

Next Steps

Resources

Related Articles

create-mcp-server v0.6.0 is out, now with stdio transport support

Deploy Your MCP Server to Google Cloud Run (For Free)

Introduction

Why Google Cloud Run?

Scaffold Your MCP Server

The Dockerfile

Set Up the gcloud CLI

Install gcloud CLI

Enable Billing

Deploy to Cloud Run

Create a New Project

Enable Required APIs

Deploy from Source

Get Your Service URL

Troubleshooting: Invalid Host Error

Test Your Deployed Server

Cleanup

What's Next?

What About Stdio Servers?

Conclusion

Resources

Related Articles

Lessons from OpenClaw's Architecture for Agent Builders

Introduction

Why OpenClaw Matters for Builders

The 4-Layer Architecture

What Runs the Agent Itself?

The Gateway Layer

The Intelligence Layer

The Lane Queue: OpenClaw's Core Innovation

The Problem

The Solution: Default Serial, Explicit Parallel

Why This Matters for Your Agents

Channel Abstraction: One Agent, Ten Platforms

Skills: Prompt Engineering as the Extension Mechanism