DEV Community: Serhii Kalyna

Vector Databases Comparison: Pinecone vs Chroma vs Weaviate (2026)

Serhii Kalyna — Fri, 08 May 2026 10:22:04 +0000

Choosing a vector database is one of the first decisions in any RAG project. Three options dominate developer usage: Pinecone, Chroma, and Weaviate. Here's a practical comparison.

Quick Overview

	Pinecone	Chroma	Weaviate
Hosting	Managed cloud only	Local or cloud	Self-hosted or cloud
Setup time	5 minutes	1 minute	10–20 minutes
Free tier	Yes (1 index)	Yes (local)	Yes (self-hosted)
Best for	Production scale	Development, prototyping	Hybrid search, complex queries

Chroma: Start Here

Chroma runs in-process — no server needed. Perfect for development and small projects.

pip install chromadb

import chromadb
from chromadb.utils import embedding_functions

client = chromadb.PersistentClient("./chroma_db")

ef = embedding_functions.SentenceTransformerEmbeddingFunction(
    model_name="all-MiniLM-L6-v2"
)

collection = client.get_or_create_collection("docs", embedding_function=ef)

collection.add(
    documents=[
        "RAG stands for Retrieval-Augmented Generation.",
        "Fine-tuning updates model weights on new data.",
        "Vector search finds semantically similar content.",
    ],
    ids=["doc1", "doc2", "doc3"],
)

results = collection.query(query_texts=["how does RAG work?"], n_results=2)
print(results["documents"])

Pros: Zero setup, runs locally, great for prototyping.
Cons: Not designed for multi-node scale, no built-in auth.

Pinecone: Managed Scale

Pinecone is a fully managed vector database. No infrastructure to run.

pip install pinecone-client sentence-transformers

from pinecone import Pinecone, ServerlessSpec
from sentence_transformers import SentenceTransformer

pc = Pinecone(api_key="YOUR_PINECONE_API_KEY")

pc.create_index(
    name="kalyna-docs",
    dimension=384,
    metric="cosine",
    spec=ServerlessSpec(cloud="aws", region="us-east-1"),
)

index = pc.Index("kalyna-docs")
model = SentenceTransformer("all-MiniLM-L6-v2")

texts = ["RAG is a retrieval technique.", "Fine-tuning changes model weights."]
embeddings = model.encode(texts).tolist()

index.upsert(vectors=[
    {"id": "v1", "values": embeddings[0], "metadata": {"text": texts[0]}},
    {"id": "v2", "values": embeddings[1], "metadata": {"text": texts[1]}},
])

query_vec = model.encode(["how to retrieve documents?"]).tolist()[0]
results = index.query(vector=query_vec, top_k=2, include_metadata=True)
for match in results.matches:
    print(match.metadata["text"], "| score:", round(match.score, 3))

Pros: Zero ops, scales automatically, fast at large scale.
Cons: Vendor lock-in, can get expensive, free tier limits.

Weaviate: Hybrid Search

Weaviate supports both vector search and keyword (BM25) search — called hybrid search.

pip install weaviate-client
docker run -p 8080:8080 cr.weaviate.io/semitechnologies/weaviate:latest

import weaviate
from weaviate.classes.config import Configure, Property, DataType

client = weaviate.connect_to_local()

client.collections.create(
    "Document",
    vectorizer_config=Configure.Vectorizer.text2vec_transformers(),
    properties=[
        Property(name="content", data_type=DataType.TEXT),
        Property(name="source", data_type=DataType.TEXT),
    ],
)

collection = client.collections.get("Document")
collection.data.insert({"content": "RAG retrieves documents at inference time.", "source": "guide"})

results = collection.query.hybrid(
    query="retrieval augmented generation",
    alpha=0.5,  # 0 = pure keyword, 1 = pure vector
    limit=2,
)
for obj in results.objects:
    print(obj.properties["content"])

client.close()

Pros: Hybrid search, strong filtering, active community.
Cons: More complex setup, steeper learning curve.

Which One to Pick?

Chroma — prototyping, demos, local development. Working in 10 minutes.

Pinecone — production, you don't want to manage infrastructure. Pay for convenience.

Weaviate — hybrid search (semantic + keyword), complex filters, multi-tenant systems.

With Claude (RAG Example)

import anthropic

def rag_answer(question: str) -> str:
    results = collection.query(query_texts=[question], n_results=3)
    context = "\n".join(results["documents"][0])

    client = anthropic.Anthropic()
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=512,
        messages=[{
            "role": "user",
            "content": f"Answer based on this context only:\n{context}\n\nQuestion: {question}"
        }]
    )
    return response.content[0].text

This pattern works identically with Pinecone or Weaviate — just swap the retrieval step.

Originally published at kalyna.pro

Building a Telegram Bot with Claude API (Python, 2026)

Serhii Kalyna — Fri, 08 May 2026 10:16:43 +0000

A Telegram bot powered by Claude gives you a personal AI assistant accessible from your phone. In this tutorial you'll build one from scratch — handling messages, keeping conversation history, and deploying it.

Prerequisites

Python 3.10+
Anthropic API key
Telegram account

Step 1: Create a Telegram Bot

Open Telegram, search for @botfather
Send /newbot and follow the prompts
Copy the bot token (looks like 7123456789:AAF...)

Step 2: Install Dependencies

pip install python-telegram-bot anthropic

Step 3: Basic Echo Bot

from telegram import Update
from telegram.ext import Application, MessageHandler, filters, ContextTypes

BOT_TOKEN = "YOUR_TELEGRAM_BOT_TOKEN"

async def handle_message(update: Update, context: ContextTypes.DEFAULT_TYPE):
    text = update.message.text
    await update.message.reply_text(f"You said: {text}")

app = Application.builder().token(BOT_TOKEN).build()
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, handle_message))
app.run_polling()

Test it first — make sure messages echo back before adding Claude.

Step 4: Add Claude

from telegram import Update
from telegram.ext import Application, MessageHandler, CommandHandler, filters, ContextTypes
import anthropic

BOT_TOKEN = "YOUR_TELEGRAM_BOT_TOKEN"
claude = anthropic.Anthropic()

conversations: dict[int, list] = {}

async def handle_message(update: Update, context: ContextTypes.DEFAULT_TYPE):
    chat_id = update.effective_chat.id
    user_text = update.message.text

    if chat_id not in conversations:
        conversations[chat_id] = []
    conversations[chat_id].append({"role": "user", "content": user_text})

    history = conversations[chat_id][-20:]

    response = claude.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        system="You are a helpful assistant. Be concise — this is a Telegram chat.",
        messages=history,
    )

    reply = response.content[0].text
    conversations[chat_id].append({"role": "assistant", "content": reply})
    await update.message.reply_text(reply)


async def reset_command(update: Update, context: ContextTypes.DEFAULT_TYPE):
    conversations.pop(update.effective_chat.id, None)
    await update.message.reply_text("Conversation reset.")


app = Application.builder().token(BOT_TOKEN).build()
app.add_handler(CommandHandler("reset", reset_command))
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, handle_message))
app.run_polling()

Step 5: Add Typing Indicator

async def handle_message(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await context.bot.send_chat_action(chat_id=update.effective_chat.id, action="typing")
    # ... rest of handler

Step 6: Handle Long Responses

Telegram has a 4096-character limit. Split long responses:

def split_message(text: str, limit: int = 4000) -> list[str]:
    if len(text) <= limit:
        return [text]
    parts = []
    while text:
        parts.append(text[:limit])
        text = text[limit:]
    return parts

# In your handler:
for part in split_message(reply):
    await update.message.reply_text(part)

Step 7: Deploy on a VPS

# /etc/systemd/system/claude-bot.service
[Unit]
Description=Claude Telegram Bot
After=network.target

[Service]
User=ubuntu
WorkingDirectory=/home/ubuntu/claude-bot
ExecStart=/usr/bin/python3 bot.py
Restart=always
Environment=ANTHROPIC_API_KEY=your-key
Environment=BOT_TOKEN=your-token

[Install]
WantedBy=multi-user.target

sudo systemctl enable claude-bot
sudo systemctl start claude-bot

Cost Estimate

With 100 daily messages (avg 200 input + 150 output tokens each) on Sonnet:

Input: ~$0.06/day
Output: ~$0.23/day
Total: ~$9/month

Add prompt caching on the system prompt to cut input costs by ~90%.

What to Build Next

/summarize command — paste a URL, get a summary
Image analysis — handle filters.PHOTO and use Claude's vision
Scheduled reminders — use job_queue from python-telegram-bot
Group chat mode — different system prompt for group vs private

Originally published at kalyna.pro

RAG vs Fine-Tuning: When to Use Which (Developer's Guide)

Serhii Kalyna — Fri, 08 May 2026 10:11:22 +0000

If you're building an LLM-powered application, you'll hit this question quickly: should I use RAG (Retrieval-Augmented Generation) or fine-tune the model? Both approaches customize LLM behavior — but they solve different problems.

What Is RAG?

RAG retrieves relevant documents at inference time and injects them into the prompt. The model stays unchanged — you're giving it fresh context per query.

import anthropic
from your_vector_db import search  # Chroma, Pinecone, etc.

client = anthropic.Anthropic()

def rag_answer(question: str) -> str:
    docs = search(question, top_k=5)
    context = "\n\n".join(docs)

    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        messages=[{
            "role": "user",
            "content": f"Context:\n{context}\n\nQuestion: {question}"
        }]
    )
    return response.content[0].text

When RAG works well:

Your knowledge base changes frequently (docs, tickets, product updates)
You need to cite sources or show evidence
You have a large corpus that won't fit in context
You want to avoid hallucinations on factual queries

What Is Fine-Tuning?

Fine-tuning continues training on a dataset of examples, updating the model's weights so it learns a new style, format, or domain.

# Fine-tuning is done via the provider's API or training pipeline.
# For open-source models, use Axolotl or Unsloth:

from transformers import AutoModelForCausalLM, Trainer, TrainingArguments

model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
# prepare dataset, define training args, run Trainer

When fine-tuning works well:

You need a specific output format (JSON schema, markdown template, code style)
You want the model to adopt a consistent persona or tone
You have 1,000+ high-quality labeled examples
Inference latency from long prompts is a bottleneck

Side-by-Side Comparison

Dimension	RAG	Fine-tuning
Knowledge source	External documents at runtime	Baked into weights at train time
Updates	Instant — just update your DB	Requires retraining
Hallucination risk	Lower (grounded in retrieved docs)	Higher
Data needed	Any documents	500–10,000+ labeled examples
Cost	Vector DB + extra tokens	GPU compute or API fine-tune fee
Latency	Slightly higher (retrieval step)	Same as base model
Best for	Factual Q&A, documentation, support	Style, format, specialized tasks

Decision Framework

Use RAG if:

Your data changes more than once a month
You need answers grounded in specific documents
You don't have labeled input→output pairs

Use fine-tuning if:

You want a consistent output format every time
You have thousands of curated examples
The task is about style/tone, not factual recall
You've already tried prompt engineering and it's not enough

Use both if:

You need domain-specific output format (fine-tuning) AND up-to-date facts (RAG)
Example: a customer support bot that answers in a specific template using fresh product docs

Quick Decision Test

Is the answer in a document I own? → RAG
Is the task about format/style, not knowledge? → Fine-tuning
Do I have 1,000+ labeled examples? → Fine-tuning is viable
Does my data change weekly? → RAG (fine-tuning won't keep up)

Practical Starting Point

For most developer projects, start with RAG. It's faster to build, easier to update, and gives you explainable results. Fine-tune only after you've validated that RAG alone can't meet your quality bar.

The best LLM applications often combine both: fine-tune for reliable output structure, add RAG for fresh knowledge.

Originally published at kalyna.pro

n8n + Claude API: Complete Automation Guide (2026)

Serhii Kalyna — Fri, 08 May 2026 10:06:01 +0000

n8n is an open-source workflow automation tool — think Zapier but self-hosted and developer-friendly. Claude handles the intelligence layer. Together they let you build automations that actually understand content, not just route it.

Prerequisites

n8n running locally or on a VPS (npx n8n or Docker)
Anthropic API key from console.anthropic.com
Basic familiarity with n8n's node interface

Step 1: Add Claude via HTTP Request Node

n8n doesn't have a native Claude node yet, but the HTTP Request node covers everything.

Configure it:

Method: POST
URL: https://api.anthropic.com/v1/messages
Headers:
  x-api-key: YOUR_ANTHROPIC_API_KEY
  anthropic-version: 2023-06-01
  Content-Type: application/json
Body (JSON):
{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "messages": [
    { "role": "user", "content": "{{ $json.input_text }}" }
  ]
}

Extract the response text with: {{ $json.content[0].text }}

Workflow 1: Email Summarizer

Automatically summarize incoming emails and send a daily digest.

Nodes: Gmail Trigger → HTTP Request (Claude) → Aggregate → Schedule Trigger → Gmail send

Claude prompt:

{
  "messages": [{
    "role": "user",
    "content": "Summarize in 2-3 bullet points. Focus on action items.\n\nSubject: {{ $json.subject }}\n\nBody: {{ $json.body }}"
  }]
}

Workflow 2: Content Classifier

Route incoming support tickets to the right team by category.

Nodes: Webhook → HTTP Request (Claude) → Switch → Slack/Email

Claude prompt:

{
  "messages": [{
    "role": "user",
    "content": "Classify this ticket into exactly one category: billing, technical, general.\nRespond with only the category word.\n\nTicket: {{ $json.message }}"
  }]
}

Then use the Switch node on {{ $json.content[0].text.trim() }}.

Workflow 3: Blog Post SEO Optimizer

Automatically improve meta descriptions for new WordPress posts.

Nodes: WordPress Trigger → HTTP Request (Claude) → WordPress update

Claude prompt:

{
  "messages": [{
    "role": "user",
    "content": "Write an SEO meta description (150-160 characters). Include the primary keyword naturally. Return only the description.\n\nTitle: {{ $json.title.rendered }}\n\nExcerpt: {{ $json.excerpt.rendered }}"
  }]
}

Handling Rate Limits

Add a Wait node (1–2 seconds) between Claude calls when processing batches.

For high-volume workflows, use Claude's Batch API (50% discount, async processing):

POST https://api.anthropic.com/v1/messages/batches

Tips for Production

Store API key in n8n's credential manager, not hardcoded
Add error handling: use an Error Trigger node to catch failures
Log inputs/outputs: write to a Google Sheet for debugging
Use system prompts: add a system field for consistent behavior

Prompt Caching in n8n

If your system prompt repeats across many workflow runs, enable caching to cut costs up to 90%:

{
  "system": [
    {
      "type": "text",
      "text": "You are an expert content editor...",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [{"role": "user", "content": "{{ $json.article }}"}]
}

n8n + Claude is one of the most practical stacks for solo developers. You get the flexibility of code with the speed of a visual builder — and Claude handles anything that requires actual understanding.

Originally published at kalyna.pro

LangChain for Beginners: Complete Guide (2026)

Serhii Kalyna — Fri, 08 May 2026 10:00:40 +0000

LangChain is a framework for building applications with LLMs. It provides abstractions for chains, memory, agents, and retrieval — so you don't have to wire everything up from scratch.

This guide gets you productive with LangChain quickly. All examples use LangChain v0.3 syntax.

Installation

pip install langchain langchain-anthropic langchain-community chromadb
export ANTHROPIC_API_KEY="your-key-here"

Core Concept: Chains

A chain is a sequence of steps: prompt → LLM → output parser.

from langchain_anthropic import ChatAnthropic
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

llm = ChatAnthropic(model="claude-sonnet-4-6")

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant."),
    ("human", "{question}"),
])

chain = prompt | llm | StrOutputParser()
response = chain.invoke({"question": "What is LangChain?"})
print(response)

The | operator connects components into a chain (LCEL — LangChain Expression Language).

Adding Memory

from langchain.memory import ConversationBufferMemory
from langchain_core.prompts import MessagesPlaceholder

memory = ConversationBufferMemory(return_messages=True)

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant."),
    MessagesPlaceholder(variable_name="history"),
    ("human", "{input}"),
])

chain = prompt | llm | StrOutputParser()

def chat(user_input: str) -> str:
    history = memory.load_memory_variables({})["history"]
    response = chain.invoke({"input": user_input, "history": history})
    memory.save_context({"input": user_input}, {"output": response})
    return response

print(chat("My name is Alex."))
print(chat("What's my name?"))  # → Alex

RAG with LangChain

from langchain_community.document_loaders import WebBaseLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_community.embeddings import HuggingFaceEmbeddings
from langchain_community.vectorstores import Chroma
from langchain.chains import RetrievalQA

loader = WebBaseLoader("https://kalyna.pro/what-is-model-context-protocol-mcp/")
docs = loader.load()

splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)
chunks = splitter.split_documents(docs)

embeddings = HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2")
vectorstore = Chroma.from_documents(chunks, embeddings)

qa = RetrievalQA.from_chain_type(
    llm=llm,
    retriever=vectorstore.as_retriever(search_kwargs={"k": 5}),
)

answer = qa.invoke("What is MCP and why does it matter?")
print(answer["result"])

Agents

Agents let the LLM decide which tools to call.

from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain.tools import tool
from langchain_core.prompts import MessagesPlaceholder
import requests

@tool
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    r = requests.get(f"https://wttr.in/{city}?format=3")
    return r.text

@tool
def calculate(expression: str) -> str:
    """Evaluate a math expression safely."""
    try:
        return str(eval(expression, {"__builtins__": {}}, {}))
    except Exception as e:
        return f"Error: {e}"

tools = [get_weather, calculate]

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant with access to tools."),
    MessagesPlaceholder("chat_history", optional=True),
    ("human", "{input}"),
    MessagesPlaceholder("agent_scratchpad"),
])

agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

result = executor.invoke({"input": "What's the weather in Kyiv and what is 15% of 340?"})
print(result["output"])

Structured Output

from pydantic import BaseModel

class Article(BaseModel):
    title: str
    summary: str
    tags: list[str]

structured_llm = llm.with_structured_output(Article)
result = structured_llm.invoke("Summarize RAG for a developer audience.")
print(result.title)
print(result.tags)

When to Use LangChain vs Raw API

Use Case	LangChain	Raw API
Quick prototype	Fast to build	Slower
Complex multi-step chains	Built-in abstractions	Manual wiring
Simple single-turn calls	Overkill	Simpler
Custom control flow	Limited	Full control
Production reliability	Needs testing	More predictable

LangChain shines for prototyping and standard patterns (RAG, agents, memory). For production apps, consider using the raw API with LangChain's components selectively.

Originally published at kalyna.pro

How to Use Claude API with Node.js (Complete Guide, 2026)

Serhii Kalyna — Fri, 08 May 2026 09:55:18 +0000

The official Anthropic SDK supports Node.js and TypeScript out of the box. This guide covers everything from installation to streaming, tool use, and production best practices.

Installation

npm install @anthropic-ai/sdk
export ANTHROPIC_API_KEY="your-key-here"

First Message

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Explain async/await in JavaScript in 3 sentences." }],
});

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

CommonJS:

const Anthropic = require("@anthropic-ai/sdk");
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

Streaming

For long responses, stream tokens as they arrive:

const stream = client.messages.stream({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Write a short story about a developer." }],
});

for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}

const finalMessage = await stream.finalMessage();
console.log("\nTotal tokens:", finalMessage.usage);

Conversation History

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const history: Anthropic.MessageParam[] = [];

async function chat(userMessage: string): Promise<string> {
  history.push({ role: "user", content: userMessage });

  const response = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 1024,
    system: "You are a helpful coding assistant.",
    messages: history,
  });

  const reply = response.content[0].text;
  history.push({ role: "assistant", content: reply });
  return reply;
}

console.log(await chat("What is a closure?"));
console.log(await chat("Show me an example."));

Tool Use (Function Calling)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const tools: Anthropic.Tool[] = [
  {
    name: "get_weather",
    description: "Get the current weather for a city",
    input_schema: {
      type: "object",
      properties: {
        city: { type: "string", description: "City name" },
      },
      required: ["city"],
    },
  },
];

async function getWeather(city: string): Promise<string> {
  const res = await fetch(`https://wttr.in/${city}?format=3`);
  return res.text();
}

async function runWithTools(question: string): Promise<string> {
  const messages: Anthropic.MessageParam[] = [{ role: "user", content: question }];

  while (true) {
    const response = await client.messages.create({
      model: "claude-sonnet-4-6",
      max_tokens: 1024,
      tools,
      messages,
    });

    if (response.stop_reason === "end_turn") {
      const textBlock = response.content.find((b) => b.type === "text");
      return textBlock?.text ?? "";
    }

    if (response.stop_reason === "tool_use") {
      messages.push({ role: "assistant", content: response.content });

      const toolResults: Anthropic.ToolResultBlockParam[] = [];
      for (const block of response.content) {
        if (block.type === "tool_use") {
          const input = block.input as { city: string };
          const result = await getWeather(input.city);
          toolResults.push({ type: "tool_result", tool_use_id: block.id, content: result });
        }
      }
      messages.push({ role: "user", content: toolResults });
    }
  }
}

console.log(await runWithTools("What's the weather in Kyiv?"));

Prompt Caching

Cache long system prompts to cut costs up to 90%:

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: "You are an expert TypeScript developer with deep knowledge of Node.js...",
      cache_control: { type: "ephemeral" },
    },
  ],
  messages: [{ role: "user", content: "How do I handle backpressure in streams?" }],
});

console.log("Cache read tokens:", response.usage.cache_read_input_tokens);

Error Handling

import { APIError, RateLimitError, APIConnectionError } from "@anthropic-ai/sdk";

async function safeCreate(content: string): Promise<string | null> {
  try {
    const response = await client.messages.create({
      model: "claude-sonnet-4-6",
      max_tokens: 512,
      messages: [{ role: "user", content }],
    });
    return response.content[0].text;
  } catch (err) {
    if (err instanceof RateLimitError) {
      console.error("Rate limited — back off and retry");
    } else if (err instanceof APIConnectionError) {
      console.error("Network error:", err.message);
    } else if (err instanceof APIError) {
      console.error(`API error ${err.status}:`, err.message);
    }
    return null;
  }
}

Express.js Integration

import express from "express";
import Anthropic from "@anthropic-ai/sdk";

const app = express();
app.use(express.json());
const client = new Anthropic();

app.post("/chat", async (req, res) => {
  const { message } = req.body;
  if (!message) return res.status(400).json({ error: "message required" });

  const response = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 1024,
    messages: [{ role: "user", content: message }],
  });

  res.json({ reply: response.content[0].text });
});

app.listen(3000, () => console.log("Server running on :3000"));

Originally published at kalyna.pro

How to Configure Cloudflare for WordPress: Caching & Security Headers

Serhii Kalyna — Fri, 08 May 2026 09:47:05 +0000

If you run a WordPress blog, Cloudflare is one of the highest-leverage free tools you can add. It sits between your visitors and your server, caches pages so your origin never gets hammered, and lets you add security headers in seconds — no plugin required. In this guide you will configure Cache Rules and Security Headers via Cloudflare Transform Rules, then verify everything with a single terminal command.

Prerequisites

A WordPress site with Cloudflare already proxying traffic (orange cloud in DNS)
Access to the Cloudflare dashboard for your domain
curl or any HTTP client for testing

Why Cloudflare Caching Matters

By default, Cloudflare proxies your traffic but does not cache HTML pages. Every visitor hits your PHP/WordPress stack directly. After enabling cache rules, Cloudflare serves cached HTML from its global edge — the server load drops to near zero for repeat visitors and page load time improves dramatically.

Without caching, every request returns CF-Cache-Status: DYNAMIC. After our rule, repeat requests return CF-Cache-Status: HIT and are served in under 200 ms from the nearest Cloudflare PoP.

Step 1: Create a Cache Rule

Navigate to Rules → Overview → Cache Rules → Create rule.

Set the rule to All incoming requests, then switch to Edit expression and paste the filter below. It caches everything except the admin panel, login page, and sessions for logged-in users:

(http.host eq "yourdomain.com"
  and not starts_with(http.request.uri.path, "/wp-admin")
  and not starts_with(http.request.uri.path, "/wp-login")
  and not starts_with(http.request.uri.path, "/login")
  and not http.cookie contains "wordpress_logged_in")

Replace yourdomain.com with your actual domain.

Under Then, configure:

Cache eligibility: Eligible for cache
Edge TTL: Ignore cache-control header → 2 hours
Browser TTL: Override origin → 1 hour

Click Deploy. Cloudflare may warn that the rule might not match — ignore it and deploy anyway if your DNS is already proxied.

Step 2: Add Security Headers

Navigate to Rules → Overview → Create rule → Response Header Transform Rule.

Name the rule Security Headers, select All incoming requests, then add four headers using Set static for each:

Strict-Transport-Security → max-age=31536000; includeSubDomains
X-Content-Type-Options → nosniff
X-Frame-Options → SAMEORIGIN
Referrer-Policy → strict-origin-when-cross-origin

Deploy the rule. These headers protect against MIME-type sniffing, clickjacking, and referrer leakage — all common vulnerabilities flagged by security scanners.

Step 3: Verify Everything

Run this single curl command to check both caching and security headers at once:

curl -sI https://yourdomain.com | grep -E "CF-Cache-Status|Strict-Transport|X-Content|X-Frame|Referrer"

Expected output after a second request (first request primes the cache):

CF-Cache-Status: HIT
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
Referrer-Policy: strict-origin-when-cross-origin

You can also verify with Python:

import requests

r = requests.get("https://yourdomain.com")
for h in ["CF-Cache-Status", "Strict-Transport-Security",
          "X-Content-Type-Options", "X-Frame-Options", "Referrer-Policy"]:
    print(f"{h}: {r.headers.get(h, 'MISSING')}")

Results

After applying both rules to kalyna.pro, here is the before/after comparison:

CF-Cache-Status: DYNAMIC → HIT
Response time (repeat visits): ~280ms → ~160ms
Security headers: 0 of 4 → 4 of 4
Origin server load: every request → only cache misses

What’s Next

Enable Auto Minify (Speed → Optimization) for JS, CSS, and HTML
Turn on Brotli compression in Speed settings
Check SSL/TLS → Full (strict) mode is enabled
Run a PageSpeed Insights test to verify Core Web Vitals

Cloudflare’s free plan covers everything in this guide. No plugins, no server access — just a few rules in the dashboard and your WordPress site is faster and more secure.

Originally published at kalyna.pro

How to Build an AI Agent with Python: Step-by-Step Tutorial (2026)

Serhii Kalyna — Fri, 08 May 2026 09:41:54 +0000

An AI agent is a program that can reason, make decisions, and call external tools to complete a task — not just answer a single question. In this tutorial you’ll build a working AI agent in Python using the Claude API, tool use (function calling), and a simple agent loop. By the end you’ll have an agent that can search the web, do math, and chain multiple actions on its own.

Prerequisites

Python 3.9+
An Anthropic API key — console.anthropic.com
Basic Python knowledge (functions, dicts)
Completed the Claude API Python guide (recommended)

What Makes an AI Agent Different From a Chatbot

A regular chatbot takes a message and returns a response. An AI agent goes further: it decides what actions to take, executes them by calling tools (Python functions), observes the results, and keeps going until the task is done.

The three core components of any agent:

LLM brain — Claude decides what to do next
Tools — Python functions the agent can call (search, calculator, file ops, APIs)
Agent loop — runs until the task is complete or the model says it’s done

Step 1: Install the SDK

pip install anthropic

Set your API key as an environment variable:

export ANTHROPIC_API_KEY="sk-ant-..."

Step 2: Define Your Tools

Tools are regular Python functions. You describe them to Claude using a JSON schema — Claude reads the description and decides when to call them.

import anthropicimport mathclient = anthropic.Anthropic()def calculate(expression: str) -> str:    """Evaluate a math expression."""    try:        result = eval(expression, {"__builtins__": {}}, {"math": math})        return str(result)    except Exception as e:        return f"Error: {e}"def search_web(query: str) -> str:    """Return search results for a query."""    # Replace with SerpAPI, Brave Search, or Tavily    return f"Top result for '{query}': AI agents use LLMs to reason and act autonomously."TOOLS = [    {        "name": "calculate",        "description": "Evaluate a mathematical expression. Use for any arithmetic or math.",        "input_schema": {            "type": "object",            "properties": {                "expression": {                    "type": "string",                    "description": "A valid Python math expression, e.g. '2 ** 10' or 'math.sqrt(144)'",                }            },            "required": ["expression"],        },    },    {        "name": "search_web",        "description": "Search the web for up-to-date information on any topic.",        "input_schema": {            "type": "object",            "properties": {"query": {"type": "string", "description": "The search query"}},            "required": ["query"],        },    },]TOOL_MAP = {"calculate": calculate, "search_web": search_web}

Step 3: Build the Agent Loop

The agent loop sends a message to Claude, checks whether it wants to call a tool, executes the tool, feeds the result back, and repeats — until Claude returns a final answer.

def run_agent(user_message: str, max_iterations: int = 10) -> str:    messages = [{"role": "user", "content": user_message}]    for i in range(max_iterations):        response = client.messages.create(            model="claude-opus-4-7",            max_tokens=4096,            tools=TOOLS,            messages=messages,        )        tool_uses = [b for b in response.content if b.type == "tool_use"]        if response.stop_reason == "end_turn" or not tool_uses:            for block in response.content:                if hasattr(block, "text"):                    return block.text            return "(no text response)"        # Add Claude's response to history        messages.append({"role": "assistant", "content": response.content})        # Execute each tool and collect results        tool_results = []        for tool_use in tool_uses:            fn = TOOL_MAP.get(tool_use.name)            result = fn(**tool_use.input) if fn else f"Unknown tool: {tool_use.name}"            tool_results.append({                "type": "tool_result",                "tool_use_id": tool_use.id,                "content": result,            })        # Feed results back to Claude        messages.append({"role": "user", "content": tool_results})    return "Max iterations reached."

Step 4: Run Your Agent

if __name__ == "__main__":    answer = run_agent("What is 2 to the power of 16?")    print("Answer:", answer)    answer = run_agent(        "Search for what an AI agent is, then calculate how many seconds are in 7 days."    )    print("Answer:", answer)

Sample output:

[iter 1] stop_reason=tool_use  → calling calculate(2 ** 16)  ← 65536[iter 2] stop_reason=end_turnAnswer: 2 to the power of 16 is 65,536.[iter 1] stop_reason=tool_use  → search_web + calculate[iter 2] stop_reason=end_turnAnswer: An AI agent is a program that uses LLMs to reason autonomously.There are 604,800 seconds in 7 days.

Complete Agent — Full Code

Here’s the entire agent in one file you can copy and run:

import anthropicimport mathclient = anthropic.Anthropic()def calculate(expression: str) -> str:    try:        return str(eval(expression, {"__builtins__": {}}, {"math": math}))    except Exception as e:        return f"Error: {e}"def search_web(query: str) -> str:    # Replace with Tavily / Brave Search / SerpAPI    return f"Search result for '{query}': [connect your real API here]"TOOLS = [    {"name": "calculate",     "description": "Evaluate a math expression (Python syntax).",     "input_schema": {"type": "object", "properties": {"expression": {"type": "string"}}, "required": ["expression"]}},    {"name": "search_web",     "description": "Search the web for current information.",     "input_schema": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}},]TOOL_MAP = {"calculate": calculate, "search_web": search_web}def run_agent(user_message: str, max_iterations: int = 10) -> str:    messages = [{"role": "user", "content": user_message}]    for _ in range(max_iterations):        response = client.messages.create(            model="claude-opus-4-7", max_tokens=4096, tools=TOOLS, messages=messages        )        tool_uses = [b for b in response.content if b.type == "tool_use"]        if response.stop_reason == "end_turn" or not tool_uses:            return next((b.text for b in response.content if hasattr(b, "text")), "")        messages.append({"role": "assistant", "content": response.content})        results = [            {"type": "tool_result", "tool_use_id": tu.id,             "content": (TOOL_MAP[tu.name](**tu.input) if tu.name in TOOL_MAP else "Unknown tool")}            for tu in tool_uses        ]        messages.append({"role": "user", "content": results})    return "Max iterations reached."if __name__ == "__main__":    task = input("Task: ")    print("\nAgent:", run_agent(task))

How to Extend Your Agent

Add Real Search

Replace the search_web stub with a real API. Good options: Tavily (built for AI agents, free tier), Brave Search API (1,000 free calls/month), or SerpAPI.

Add File Operations

def read_file(path: str) -> str:    with open(path) as f:        return f.read()def write_file(path: str, content: str) -> str:    with open(path, "w") as f:        f.write(content)    return f"Written {len(content)} chars to {path}"

Add Memory

Pass the full messages list between sessions by saving it to a JSON file or SQLite database. The agent will remember previous interactions.

Multi-Agent Systems

One agent can call another as a tool. A planner agent breaks a task into subtasks; worker agents execute each one. This pattern scales to complex workflows and is the foundation of MCP.

Key Concepts Recap

Tool use — Claude decides when to call a function; you define what it does
Agent loop — keep calling the API until stop_reason == "end_turn" with no pending tool calls
Tool results — always return results as a tool_result block with the matching tool_use_id
Max iterations — always set a cap to prevent infinite loops
Model choice — claude-opus-4-7 for complex reasoning; claude-haiku-4-5-20251001 for fast, cheap subtasks

What’s Next?

You’ve built a working AI agent from scratch. From here you can:

Connect a real search API (Tavily, Brave) for live information
Add persistent memory — store conversation history in SQLite between sessions
Wrap this agent in a Telegram bot or REST API
Read the Anthropic tool use docs for parallel tool calls and advanced patterns
Explore Model Context Protocol (MCP) — a standard for connecting agents to external services

Originally published at kalyna.pro

Prompt Engineering Guide for Developers: Best Practices & Techniques (2026)

Serhii Kalyna — Fri, 08 May 2026 09:36:42 +0000

Prompt engineering is the practice of designing inputs that get the best output from an LLM. For developers building on the Claude API, it’s less about “magic phrases” and more about clear communication with a reasoning system. This guide covers the core techniques — with working Python examples — so you can write prompts that are reliable, testable, and production-ready.

1. Use a System Prompt to Set Context

The system prompt is the most powerful tool you have. It defines Claude’s role, constraints, and output style for the entire conversation.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system="You are a senior Python developer. Answer concisely. Use code examples. Avoid unnecessary explanations.",
    messages=[
        {"role": "user", "content": "How do I read a JSON file in Python?"}
    ]
)
print(response.content[0].text)

A well-crafted system prompt replaces dozens of instructions repeated in every user message. Define who Claude is, what it should focus on, and how it should respond.

2. Be Specific — Avoid Vague Instructions

Vague prompts produce vague responses. The more precisely you describe the task, the more reliable the output.

# ❌ Vague
"Summarize this article."

# ✅ Specific
"Summarize this article in 3 bullet points. Each point must be under 20 words. Focus on technical details relevant to Python developers."

Specify: format, length, tone, audience, constraints. Everything you leave out is filled in by Claude’s defaults.

3. Few-Shot Prompting: Show Examples

If you need a specific format, show it. Few-shot examples are more reliable than instructions alone.

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=256,
    system="You classify support tickets into categories.",
    messages=[
        {"role": "user", "content": "Ticket: 'My payment failed'
Category:"},
        {"role": "assistant", "content": "billing"},
        {"role": "user", "content": "Ticket: 'App crashes on login'
Category:"},
        {"role": "assistant", "content": "bug"},
        {"role": "user", "content": "Ticket: 'How do I export my data?'
Category:"},
    ]
)
print(response.content[0].text)  # → "feature-request" or "support"

Two or three examples are usually enough to lock in the pattern. More than five rarely adds value.

4. Chain of Thought: Ask Claude to Think Step by Step

For complex reasoning, multi-step math, or code generation, asking Claude to think before answering significantly improves accuracy.

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": """A server processes 1,200 requests/minute.
Each request takes on average 80ms. How many concurrent workers are needed?

Think through this step by step before giving the final answer."""
    }]
)
print(response.content[0].text)

This works because it forces Claude to “show its work” instead of jumping to an answer. The reasoning is visible, debuggable, and usually correct.

5. Request Structured Output (JSON)

When integrating Claude into a pipeline, you often need structured data, not prose. Ask for JSON and validate it.

import json

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=512,
    system="You extract information from text. Always respond with valid JSON only. No explanations.",
    messages=[{
        "role": "user",
        "content": """Extract from this job posting:
'Senior Python Developer at Acme Corp. 5+ years required. Remote. $120k-$150k.'

Respond as JSON with keys: title, company, experience_years, remote, salary_min, salary_max."""
    }]
)

data = json.loads(response.content[0].text)
print(data["salary_min"])  # → 120000

Tips for reliable JSON output:

Say “valid JSON only” and “no explanations” in the system prompt
Provide the exact key names you need
Use json.loads() and wrap in a try/except for production
For complex schemas, paste in a JSON Schema or example object

6. Constrain the Output Format

Tell Claude exactly how to format the response — length, structure, and style.

# Request a specific markdown structure
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=800,
    system="""You write technical documentation.
Format rules:
- Start with a one-sentence summary
- Use ## headings for sections
- Use code blocks with language tags
- Maximum 400 words total""",
    messages=[{"role": "user", "content": "Document the Python `requests.get()` function."}]
)

7. Use XML Tags to Structure Complex Prompts

When your prompt contains multiple components (context, instructions, data), use XML-style tags to separate them clearly. Claude handles structured prompts better than long walls of text.

user_prompt = """

You are reviewing a pull request for a Python web service.

def get_user(user_id):
    query = f"SELECT * FROM users WHERE id = {user_id}"
    return db.execute(query)

Review this code. Identify security issues. Suggest fixes with corrected code.

"""

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[{"role": "user", "content": user_prompt}]
)
print(response.content[0].text)

8. Control Temperature and Parameters

# Deterministic output (code, data extraction) — use low temperature
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    temperature=0.0,   # Fully deterministic
    messages=[{"role": "user", "content": "Write a Python function to validate an email address."}]
)

# Creative output (brainstorming, writing) — higher temperature
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    temperature=1.0,   # More varied
    messages=[{"role": "user", "content": "Give me 10 creative names for a developer tool."}]
)

temperature=0 — deterministic, best for code and structured data
temperature=0.5–0.7 — balanced, good for most tasks
temperature=1.0 — creative, more varied responses

9. Prompt Caching for Repeated Context

If you send the same large context (docs, codebase, rules) with every request, use prompt caching to cut latency and cost by up to 90%.

# Mark stable content as cacheable
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are a code reviewer. Follow these rules: ...",
        },
        {
            "type": "text",
            "text": open("codebase_context.txt").read(),  # Large, stable content
            "cache_control": {"type": "ephemeral"},        # Cache this
        }
    ],
    messages=[{"role": "user", "content": "Review the authentication module."}]
)

Cached content is reused for up to 5 minutes. Ideal for: system prompt docs, few-shot examples, or any context that doesn’t change between requests.

10. Common Mistakes to Avoid

Over-constraining — too many rules can make Claude overly cautious. Give it room to reason.
Ambiguous pronouns — “fix it” is vague. Say “fix the SQL injection vulnerability in the function above.”
Missing context — Claude doesn’t know your codebase, conventions, or audience unless you tell it.
No output format — without a format spec, responses vary. Always define the expected structure.
Ignoring the system prompt — putting everything in the user message loses the most powerful lever.
One-shot testing — test prompts with at least 10–20 different inputs before using in production.

Prompt Engineering Checklist

Define a clear system prompt with role, constraints, and format rules
Specify the output format (JSON, markdown, plain text, bullets)
Include 2–3 examples if a specific pattern is needed
Add “think step by step” for complex reasoning tasks
Use XML tags to separate context, data, and instructions
Set temperature=0 for deterministic tasks
Use prompt caching for large, reused contexts
Test across edge cases before shipping

What’s Next?

Prompt engineering is the foundation — combine it with the right tools to build reliable systems:

Build an AI agent that uses prompts + tool calling to complete complex tasks
Claude API Python tutorial — start here if you haven’t set up the SDK yet
Model Context Protocol (MCP) — connect Claude to external tools with structured prompts
Read the Anthropic prompt engineering docs for advanced techniques like extended thinking

Originally published at kalyna.pro

RAG Tutorial with Python: Build a Retrieval-Augmented Generation System

Serhii Kalyna — Fri, 08 May 2026 09:32:03 +0000

LLMs are powerful but they only know what was in their training data. RAG (Retrieval-Augmented Generation) solves this: before generating an answer, retrieve the most relevant documents from your own knowledge base and include them in the prompt. The result is an LLM that answers accurately from your data, not guesses.

This tutorial builds a complete RAG system from scratch — embeddings, vector search, and Claude for generation.

How RAG Works

Index — convert your documents into embedding vectors and store them
Retrieve — embed the user's query and find the most similar documents by cosine similarity
Generate — pass the retrieved documents as context to the LLM and ask it to answer

The LLM never sees your entire knowledge base — only the top-K most relevant chunks. This keeps prompts focused and costs predictable.

Prerequisites

pip install anthropic sentence-transformers numpy

sentence-transformers provides a local embedding model (~80MB) — no external API key needed for the retrieval step. anthropic handles generation.

Step 1: Define Your Knowledge Base

In production, this comes from chunked PDFs, database exports, or wiki pages. For this tutorial we use a list of strings:

# Your knowledge base — in production this comes from PDFs, DBs, wikis, etc.documents = [    "Claude is an AI assistant made by Anthropic. It supports tool use, prompt caching, and vision.",    "The Claude API uses token-based pricing. Sonnet costs $3/MTok input and $15/MTok output.",    "Prompt caching caches prompt prefixes for 5 minutes, saving up to 90% on repeated calls.",    "The Batch API processes requests asynchronously within 24 hours at a 50% discount.",    "Claude Haiku is the fastest and cheapest model, ideal for classification and extraction.",    "Model Context Protocol (MCP) is an open standard by Anthropic for connecting AI to tools.",]

Chunking strategy matters: chunks should be semantically coherent (one idea per chunk) and roughly 300–500 tokens each.

Step 2: Build the Vector Store

Embed every document once at startup and store the vectors as a NumPy array:

from sentence_transformers import SentenceTransformerimport numpy as npmodel = SentenceTransformer("all-MiniLM-L6-v2")  # ~80MB, runs locally, no API key needed# Build the vector store once at startupdoc_embeddings = model.encode(documents, normalize_embeddings=True)# Shape: (6, 384) — one 384-dim vector per document

all-MiniLM-L6-v2 is fast and compact (384-dim embeddings). For production, consider bge-large-en-v1.5 or OpenAI's text-embedding-3-small for higher quality.

Step 3: Retrieve Relevant Documents

Cosine similarity between normalized vectors is just a dot product — fast and dependency-free with NumPy:

def retrieve(query: str, top_k: int = 3) -> list[str]:    query_vec = model.encode([query], normalize_embeddings=True)    # Cosine similarity = dot product on L2-normalized vectors    scores = (doc_embeddings @ query_vec.T).flatten()    top_indices = np.argsort(scores)[::-1][:top_k]    return [documents[i] for i in top_indices]# Test retrievalresults = retrieve("How much does Claude Sonnet cost?")for doc in results:    print("-", doc)

Step 4: Generate the Answer with Claude

Pass the retrieved documents as context and let Claude synthesize the answer:

import anthropicclient = anthropic.Anthropic()def answer(question: str) -> str:    context_docs = retrieve(question, top_k=3)    context = "\n\n".join(f"- {doc}" for doc in context_docs)    response = client.messages.create(        model="claude-sonnet-4-6",        max_tokens=512,        system="Answer questions using ONLY the provided context. If the answer is not in the context, say so.",        messages=[{            "role": "user",            "content": f"Context:\n{context}\n\nQuestion: {question}"        }]    )    return response.content[0].text

The system prompt instruction — "answer ONLY from the provided context" — is what keeps the model grounded. Without it, Claude may mix retrieval context with its own training knowledge.

Step 5: Run It

questions = [    "What is prompt caching and how much can it save?",    "Which Claude model is best for classification?",    "What is MCP?",]for q in questions:    print(f"Q: {q}")    print(f"A: {answer(q)}")    print()

Optimize with Prompt Caching

If your system prompt is long and repeated across many queries, cache it to save up to 90% on input costs:

def answer_with_cache(question: str) -> str:    context_docs = retrieve(question, top_k=3)    context = "\n\n".join(f"- {doc}" for doc in context_docs)    response = client.messages.create(        model="claude-sonnet-4-6",        max_tokens=512,        system=[{            "type": "text",            "text": "Answer questions using ONLY the provided context. If the answer is not in the context, say so.",            "cache_control": {"type": "ephemeral"}  # cache the system prompt prefix        }],        messages=[{            "role": "user",            "content": f"Context:\n{context}\n\nQuestion: {question}"        }]    )    return response.content[0].text

Production Considerations

Vector database — replace NumPy with ChromaDB, Pinecone, or pgvector for persistence and scale
Chunking — use overlapping chunks (e.g., 400 tokens with 50-token overlap) to avoid splitting context at boundaries
Reranking — after top-K retrieval, apply a cross-encoder reranker for higher precision
Metadata filtering — filter by date, category, or source before semantic search
Evaluation — measure retrieval recall and answer faithfulness with frameworks like RAGAS

Summary

RAG in its simplest form is three steps: embed → retrieve → generate. The implementation above is production-ready for small to medium corpora. As your knowledge base grows, swap NumPy for a proper vector database — the retrieval and generation logic stays identical.

Originally published at kalyna.pro

How to Build an MCP Server with Claude: Complete Tutorial (2026)

Serhii Kalyna — Fri, 08 May 2026 09:30:50 +0000

The Model Context Protocol (MCP) lets you expose custom tools and data sources to Claude in a standardized way. Instead of hardcoding tool definitions in every app, you build an MCP server once and connect it to Claude Desktop, Claude Code, or any MCP-compatible client. In this tutorial you’ll build a working MCP server in Python from scratch, add real tools, and connect it to Claude.

Prerequisites

Python 3.10+
An Anthropic API key — console.anthropic.com
Claude Desktop or Claude Code installed
Basic Python knowledge (functions, async)
Read What is MCP? first (optional but recommended)

What Is an MCP Server, Exactly?

An MCP server is a lightweight process that exposes tools, resources, and prompts to an LLM client over a standard protocol. Think of it as a plugin system for Claude:

Tools — functions Claude can call (search, read files, query a database)
Resources — data Claude can read (files, API responses, live data)
Prompts — reusable prompt templates with arguments

Claude decides when to call your tools based on the user’s message — you just define what’s available. The MCP protocol handles the transport (stdio or HTTP), so you focus only on your tool logic.

Step 1: Install the MCP SDK

Install the official Python MCP SDK:

pip install mcp

This installs the mcp package with everything you need to build and run a server.

Step 2: Create Your First MCP Server

Create a file called server.py:

int:
"""Add two numbers together."""
return a + b

@mcp.tool()
def get_weather(city: str) -> str:
"""Get current weather for a city (stub)."""
return f"Weather in {city}: 22°C, partly cloudy"

if name == "main":
mcp.run()" style="color:#E6E6E6;display:none" aria-label="Copy" class="code-block-pro-copy-button">

from mcp.server.fastmcp import FastMCP

# Create the server
mcp = FastMCP("my-tools")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b

@mcp.tool()
def get_weather(city: str) -> str:
    """Get current weather for a city (stub)."""
    return f"Weather in {city}: 22°C, partly cloudy"

if __name__ == "__main__":
    mcp.run()

shell

The @mcp.tool() decorator registers a function as a tool Claude can call. The docstring becomes the tool description Claude uses when deciding whether to call it — write clear, specific descriptions.

Step 3: Test Your Server Locally

Use the MCP dev inspector to test your tools interactively:

mcp dev server.py

python

This opens an interactive inspector in your browser where you can call tools manually and see the JSON request/response. Verify your tools return the expected output before connecting to Claude.

Step 4: Add Real Tools

Let’s build something more useful — a file reader and a URL fetcher:

str:
"""Read the contents of a local file by path."""
p = pathlib.Path(path)
if not p.exists():
return f"Error: file not found: {path}"
if p.stat().st_size > 100_000:
return "Error: file too large (>100KB)"
return p.read_text(encoding="utf-8", errors="replace")

@mcp.tool()
def fetch_url(url: str) -> str:
"""Fetch the text content of a URL (first 5000 chars)."""
if not url.startswith(("http://", "https://")):
return "Error: only http/https URLs allowed"
with urllib.request.urlopen(url, timeout=10) as resp:
content = resp.read().decode("utf-8", errors="replace")
return content[:5000]

@mcp.tool()
def list_directory(path: str = ".") -> str:
"""List files in a directory."""
entries = sorted(pathlib.Path(path).iterdir())
lines = []
for e in entries:
kind = "DIR " if e.is_dir() else "FILE"
lines.append(f"{kind} {e.name}")
return "\n".join(lines) if lines else "(empty)"

if name == "main":
mcp.run()" style="color:#E6E6E6;display:none" aria-label="Copy" class="code-block-pro-copy-button">

from mcp.server.fastmcp import FastMCP
import urllib.request
import pathlib

mcp = FastMCP("dev-tools")

@mcp.tool()
def read_file(path: str) -> str:
    """Read the contents of a local file by path."""
    p = pathlib.Path(path)
    if not p.exists():
        return f"Error: file not found: {path}"
    if p.stat().st_size > 100_000:
        return "Error: file too large (>100KB)"
    return p.read_text(encoding="utf-8", errors="replace")

@mcp.tool()
def fetch_url(url: str) -> str:
    """Fetch the text content of a URL (first 5000 chars)."""
    if not url.startswith(("http://", "https://")):
        return "Error: only http/https URLs allowed"
    with urllib.request.urlopen(url, timeout=10) as resp:
        content = resp.read().decode("utf-8", errors="replace")
    return content[:5000]

@mcp.tool()
def list_directory(path: str = ".") -> str:
    """List files in a directory."""
    entries = sorted(pathlib.Path(path).iterdir())
    lines = []
    for e in entries:
        kind = "DIR " if e.is_dir() else "FILE"
        lines.append(f"{kind}  {e.name}")
    return "\n".join(lines) if lines else "(empty)"

if __name__ == "__main__":
    mcp.run()

Notice the safety checks: we validate the URL scheme and limit file size. Claude will call your tools with whatever arguments it thinks are correct — always validate inputs on the server side.

Step 5: Expose Resources (Optional)

Resources are read-only data sources Claude can reference by URI. Unlike tools, Claude reads resources proactively rather than calling them on demand:

str:
"""Return the current application configuration."""
return """
APP_ENV=production
MAX_RETRIES=3
TIMEOUT=30
""".strip()

@mcp.resource("docs://readme")

def get_readme() -> str:
"""Return project README."""
return pathlib.Path("README.md").read_text()" style="color:#E6E6E6;display:none" aria-label="Copy" class="code-block-pro-copy-button">

@mcp.resource("config://app")
def get_app_config() -> str:
    """Return the current application configuration."""
    return """
APP_ENV=production
MAX_RETRIES=3
TIMEOUT=30
    """.strip()

@mcp.resource("docs://readme")  
def get_readme() -> str:
    """Return project README."""
    return pathlib.Path("README.md").read_text()

json

Step 6: Connect to Claude Desktop

Once your server works in the inspector, add it to Claude Desktop. Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "dev-tools": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

shell

Restart Claude Desktop. You’ll see a hammer icon in the chat interface — that confirms your MCP server is connected. Claude will now automatically use your tools when relevant.

Step 7: Connect to Claude Code

Claude Code (the CLI) also supports MCP servers. Add your server with:

claude mcp add dev-tools python /absolute/path/to/server.py

python

Or add it to your project’s .claude/settings.json for per-project tools. Run claude mcp list to verify it’s registered.

Debugging Tips

If your server isn’t connecting or tools aren’t being called:

Check the server logs — MCP SDK prints errors to stderr
Run mcp dev server.py and test tools manually in the inspector first
Use absolute paths in claude_desktop_config.json — relative paths fail silently
Make sure python in the config points to the right virtualenv
Check Claude Desktop logs: ~/Library/Logs/Claude/ (macOS)

Complete Working Server

Here’s the full production-ready example with error handling:

str:
"""Read a local file. Returns file contents or an error message."""
try:
p = pathlib.Path(path).resolve()
if not p.exists():
return f"Error: {path} does not exist"
if not p.is_file():
return f"Error: {path} is not a file"
if p.stat().st_size > 200_000:
return "Error: file is larger than 200KB — too large to read"
return p.read_text(encoding="utf-8", errors="replace")
except PermissionError:
return f"Error: permission denied reading {path}"

@mcp.tool()
def fetch_url(url: str, max_chars: int = 5000) -> str:
"""Fetch text content from a URL. Returns up to max_chars characters."""
if not url.startswith(("http://", "https://")):
return "Error: only http/https URLs are allowed"
try:
req = urllib.request.Request(url, headers={"User-Agent": "MCP-Server/1.0"})
with urllib.request.urlopen(req, timeout=15) as resp:
content = resp.read().decode("utf-8", errors="replace")
return content[:max_chars]
except urllib.error.URLError as e:
return f"Error fetching URL: {e}"

@mcp.tool()
def list_directory(path: str = ".") -> str:
"""List files and directories at the given path."""
try:
p = pathlib.Path(path)
if not p.exists():
return f"Error: {path} does not exist"
entries = sorted(p.iterdir())
lines = [f"{'DIR ' if e.is_dir() else 'FILE'} {e.name}" for e in entries]
return "\n".join(lines) if lines else "(empty directory)"
except PermissionError:
return f"Error: permission denied for {path}"

@mcp.tool()
def write_file(path: str, content: str) -> str:
"""Write text content to a file. Creates the file if it does not exist."""
try:
p = pathlib.Path(path)
p.parent.mkdir(parents=True, exist_ok=True)
p.write_text(content, encoding="utf-8")
return f"Written {len(content)} characters to {path}"
except Exception as e:
return f"Error writing file: {e}"

if name == "main":
mcp.run()" style="color:#E6E6E6;display:none" aria-label="Copy" class="code-block-pro-copy-button">

from mcp.server.fastmcp import FastMCP
import pathlib
import urllib.request
import urllib.error
import json

mcp = FastMCP("dev-tools", version="1.0.0")

@mcp.tool()
def read_file(path: str) -> str:
    """Read a local file. Returns file contents or an error message."""
    try:
        p = pathlib.Path(path).resolve()
        if not p.exists():
            return f"Error: {path} does not exist"
        if not p.is_file():
            return f"Error: {path} is not a file"
        if p.stat().st_size > 200_000:
            return "Error: file is larger than 200KB — too large to read"
        return p.read_text(encoding="utf-8", errors="replace")
    except PermissionError:
        return f"Error: permission denied reading {path}"

@mcp.tool()
def fetch_url(url: str, max_chars: int = 5000) -> str:
    """Fetch text content from a URL. Returns up to max_chars characters."""
    if not url.startswith(("http://", "https://")):
        return "Error: only http/https URLs are allowed"
    try:
        req = urllib.request.Request(url, headers={"User-Agent": "MCP-Server/1.0"})
        with urllib.request.urlopen(req, timeout=15) as resp:
            content = resp.read().decode("utf-8", errors="replace")
        return content[:max_chars]
    except urllib.error.URLError as e:
        return f"Error fetching URL: {e}"

@mcp.tool()
def list_directory(path: str = ".") -> str:
    """List files and directories at the given path."""
    try:
        p = pathlib.Path(path)
        if not p.exists():
            return f"Error: {path} does not exist"
        entries = sorted(p.iterdir())
        lines = [f"{'DIR ' if e.is_dir() else 'FILE'} {e.name}" for e in entries]
        return "\n".join(lines) if lines else "(empty directory)"
    except PermissionError:
        return f"Error: permission denied for {path}"

@mcp.tool()
def write_file(path: str, content: str) -> str:
    """Write text content to a file. Creates the file if it does not exist."""
    try:
        p = pathlib.Path(path)
        p.parent.mkdir(parents=True, exist_ok=True)
        p.write_text(content, encoding="utf-8")
        return f"Written {len(content)} characters to {path}"
    except Exception as e:
        return f"Error writing file: {e}"

if __name__ == "__main__":
    mcp.run()

Next Steps

Once your basic server is working, you can extend it with:

Database tools — wrap SQLite, PostgreSQL, or any ORM queries as MCP tools
API integrations — GitHub, Jira, Slack, Notion — give Claude access to your workflow
HTTP transport — run your server as a persistent HTTP endpoint instead of stdio for remote access
Authentication — add API key checks or OAuth if exposing the server remotely
Browse the official MCP server registry for inspiration and ready-made servers

Conclusion

Building an MCP server gives Claude a structured, reusable way to interact with your environment. You define the tools once, and Claude uses them intelligently across all MCP clients. Start with the FastMCP decorator pattern, test with mcp dev, then connect to Claude Desktop or Claude Code. From there the sky’s the limit — database access, API integrations, custom workflows.

Have questions or built something cool with MCP? Drop a comment below.

Originally published at kalyna.pro

Claude API Pricing Explained: What Does It Really Cost in 2025?

Serhii Kalyna — Fri, 08 May 2026 09:26:52 +0000

If you're building with the Claude API, pricing will be one of your first questions. The good news: it's entirely token-based, predictable, and — with the right techniques — very affordable even at scale. This guide breaks down exactly what you'll pay and how to minimize it.

How Claude API Pricing Works

Claude charges per token — roughly 4 characters of English text. Every API call has two costs:

Input tokens — your prompt, system message, and conversation history
Output tokens — the model's response (typically 3–5× more expensive)

Prices are listed per 1 million tokens (MTok).

Claude Model Pricing (May 2025)

ModelInput (per MTok)Output (per MTok)Best forClaude Haiku 4.5$0.80$4.00High-volume, simple tasksClaude Sonnet 4.6$3.00$15.00Balanced — most projectsClaude Opus 4.7$15.00$75.00Complex reasoning, low volume

Rule of thumb: Start with Sonnet. Switch to Haiku for repetitive tasks (classification, extraction). Use Opus only when you need the extra reasoning power.

Real-World Cost Estimates

Let's make this concrete. Here's a Python helper to estimate monthly costs:

def estimate_cost(input_tokens: int, output_tokens: int, model: str = "sonnet") -> float:    prices = {        "haiku":   (0.80, 4.00),   # per 1M tokens (input, output)        "sonnet":  (3.00, 15.00),        "opus":    (15.00, 75.00),    }    inp, out = prices[model]    return (input_tokens / 1_000_000 * inp) + (output_tokens / 1_000_000 * out)# Example: 1000 API calls, avg 500 input + 300 output tokens eachcalls = 1000cost = estimate_cost(calls * 500, calls * 300, model="sonnet")print(f"Monthly estimate: ${cost:.2f}")# → Monthly estimate: $5.99

Some typical scenarios on Sonnet:

Use CaseCalls/dayTokens/callMonthly costSimple chatbot1,000500 in / 300 out~$6Document summarizer2003,000 in / 500 out~$7Code review tool1002,000 in / 1,000 out~$6Classification pipeline10,000200 in / 50 out~$4

Cut Costs with Prompt Caching (Up to 90% Off)

Prompt caching is the single biggest lever for reducing API costs. When you mark a portion of your prompt with cache_control, Claude stores it server-side for 5 minutes. Subsequent requests that reuse that prefix pay only 10% of normal input cost for the cached portion.

Cache writes cost 25% more than normal input — but you break even after just 2 cache hits, and save heavily after that. Perfect for:

Long system prompts repeated across many calls
Large document contexts (PDFs, codebases) queried multiple times
Few-shot example sets used in a session

import anthropicclient = anthropic.Anthropic()# System prompt cached after first request (5-minute TTL)response = client.messages.create(    model="claude-sonnet-4-6",    max_tokens=1024,    system=[        {            "type": "text",            "text": "You are a helpful coding assistant with deep Python expertise.",            "cache_control": {"type": "ephemeral"}  # cache this prefix        }    ],    messages=[{"role": "user", "content": "Explain list comprehensions."}])# Check cache performance in response headers / usageusage = response.usageprint(f"Input tokens:         {usage.input_tokens}")print(f"Cache write tokens:   {usage.cache_creation_input_tokens}")print(f"Cache read tokens:    {usage.cache_read_input_tokens}")

Batch API: 50% Discount for Async Workloads

The Batch API processes requests asynchronously (within 24 hours) at 50% off standard pricing. Ideal for:

Overnight data processing pipelines
Bulk content generation or classification
Offline analysis that doesn't need real-time responses

For Sonnet, that's $1.50/MTok input and $7.50/MTok output — cheaper than Haiku at standard rates.

Practical Tips to Keep Costs Low

Log token usage — every response includes usage.input_tokens and usage.output_tokens. Track them from day one.
Use max_tokens — always set a reasonable limit to prevent runaway outputs.
Cache aggressively — anything over 1,024 tokens that repeats is a caching candidate.
Right-size your model — Haiku at $0.80/MTok handles most classification, extraction, and short Q&A tasks perfectly well.
Use Batch API for anything that doesn't need real-time responses.
Compress history in long conversations — summarize older turns instead of passing them verbatim.

Bottom Line

Claude API pricing is straightforward and highly controllable. For most developer projects, you're looking at $5–30/month at moderate scale. With prompt caching and the right model tier, costs stay low even as usage grows. The key is to measure from the start — token counts are always in the response, so there's no excuse not to track them.

Originally published at kalyna.pro