DEV Community: Ely

Building an MCP server: teaching AI assistants about backups

Ely — Sun, 15 Feb 2026 19:30:54 +0000

My journey into the Model Context Protocol

Today I built a Model Context Protocol (MCP) server to connect AI assistants with Bareos backup infrastructure. Join me as I walk through building this integration and share what I learned along the way.

Or if you just want to see the result, check it out at https://github.com/edeckers/bareos-mcp-server

Photo by János Venczák on Unsplash

What is MCP?

The Model Context Protocol is Anthropic's solution for giving AI assistants like Claude access to external tools and data. It's a JSON-RPC based protocol that runs over stdin/stdout.

The concept is straightforward: instead of manually running bconsole commands, copying output, and pasting it into a chat, you ask "show me the last 10 backup jobs" and the AI fetches it directly from your Bareos Director through the MCP server.

Why Bareos?

I've been managing my backups with Bareos for a while now. And while bconsole is powerful, it requires remembering specific command syntax for listing jobs, checking storage pools, or viewing client status.

Being able to query backup infrastructure conversationally, like "why did last night's backup fail?" or "how much storage is left in the Full pool?" seemed like a practical use case for MCP.

The journey

Understanding the Protocol

MCP is a JSON-RPC protocol with three main operations:

Initialize: Server announces capabilities
List tools: Server describes available tools
Call tool: Client executes a tool with arguments

And that's pretty much it. The rest is tool implementation and error handling.

Read-Only by design for now

I deliberately kept everything read-only initially, so no starting jobs, deleting volumes, or pruning backups. Just queries. This was a practical decision: I wanted to understand the protocol and tool design without worrying about accidentally breaking production backups. Mutable actions are planned for later versions.

Emergent behavior

The interesting part came when I realized Claude could answer questions I hadn't explicitly coded for, and which would require multiple bconsole queries. Ask it "Which clients haven't backed up in the last 24 hours?" and it will:

Call list_jobs to get recent jobs
Call list_clients to get all clients
Compare the two
Provide an answer

I built primitive tools; the AI combines them to answer complex queries. That's the real value of MCP: you're building composable primitives, not a comprehensive API.

What I learned

Tool design matters

The quality of tool descriptions directly impacts how well the AI uses them. Vague descriptions lead to mistakes. Clear, specific descriptions with parameter explanations work reliably.

For example:

Don't do this: "List jobs"
Do this: "List recent backup jobs. Use the limit parameter to control how many jobs are returned (default: 50)"

Testing without an AI assistant

You can test MCP servers with just echo and pipes:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
./bareos-mcp-server

No need to configure Claude Desktop or spin up a full client. Just send JSON-RPC over stdin. It is actually how Claude will interact with the server, and it is very useful for debugging.

Build for composition

Don't try to predict every query users might want. Build small, focused tools that can be combined. The AI is surprisingly good at figuring out how to compose them.

Recommendations for building MCP servers

Start with a tool you already use. Pick something you interact with regularly, you'll understand the use cases and catch issues faster.
Begin with one tool. Get one tool working end-to-end before adding more. I started with list_jobs and expanded from there.
Write clear descriptions. Tool descriptions are the AI's only guide.
Be specific about parameters, formats, and return values.
Test with raw JSON-RPC first. Verify your tools work with manual calls before involving an AI assistant. Faster iteration, clearer debugging.
Start read-only if safety matters. Read-only operations let you learn the protocol without risking production systems. Add mutations once you're confident.

Try it yourself

The code is open source at https://github.com/edeckers/bareos-mcp-server with installation instructions for both Claude Code and Claude Desktop.

Useful resources

Building your own MCP server? These resources helped me:

Built something with MCP or considering it? Let me know in the comments!

If the Dutch language doesn't scare you, and you'd like to know more about what keeps me busy aside from my pet projects, check my company website https://branie.it! Maybe we can work together on something someday :)

Building Flipr: a URL shortener, one commit at a time

Ely — Sun, 09 Nov 2025 21:09:46 +0000

Part 1: the simplest thing that could possibly work

Welcome to the first post in a series that dives into the world of distributed systems building on Kubernetes, using as a subject the "Todo application" of systems design: a URL shortener we'll call Flipr 🐬.

The goal is to build an actual, functioning, deployable system, designed to scale from a single instance to a distributed cluster on Kubernetes.

Photo by Louan García on Unsplash

What this series is and what it is not

This series focuses on building a distributed, scalable URL shortener and the architectural decisions behind it. To keep that focus sharp, I'm intentionally omitting several things that would be critical in a production system, such as:

No unit tests: focus is on architectural evolution, not a production-ready codebase
Minimal input validation: basic checks only, not production-grade security hardening
No abuse prevention: there will be rate limiting, but anti-spam measures won't be covered
No user accounts: this is a simple shortener demonstrating distributed systems concepts

So, if you're looking for a complete, production-ready URL shortener, check GitHub and take your pick. But if you want to understand how distributed systems are built and how to benchmark architectural improvements, you're in the right place!

Requirements & scale targets

Before we write any code, let's define what we're building toward. I'm intentionally keeping the performance targets vague, because actual throughput and latency will depend entirely on the hardware you deploy to.

And while we don't define hard performance targets upfront, we'll be benchmarking each iteration and comparing results throughout this series. This way, we can demonstrate that our architectural evolution actually improves performance and scalability, not just adds complexity.

Functional Requirements:

Short Code Specifications:
- Length: 6-7 characters
- Character set: a-z, A-Z, 0-9 (62 characters)
- Namespace: 62^7 = ~3.5 trillion possible codes
URL Constraints:
- Max original URL length: 2,048 characters (browser-safe)
- Short code lifetime: Indefinite (no expiration)

Design Goals:

Horizontal Scalability: add more instances to handle increased load, rather than relying on bigger servers
Read-Heavy workload: expect redirects to vastly outnumber shortening requests (typical 10:1 ratio or higher)
Storage growth: design for millions of short codes with room to grow
Low latency: keep both shortening and redirects fast (sub-100ms when possible)

So where do we start?

The best place to start is with the simplest possible implementation of the core functionality: shortening URLs and redirecting to them. From here, we can iteratively add features, optimizations, and infrastructure components, each time motivated by a real need that arises from the limitations of the previous version.

Before we dive into code, a quick note on approach (you should skip this if you don't care for me getting all philosophical)

When you start simple and get something working, storage methods, scaling strategies, and database schemas follow naturally from the problems you encounter, not from upfront speculation.

Over my career, I've met countless developers who approach this in the exact reverse order, and I used to be one of them: I'd start with the database model, design the perfect schema, plan the caching strategy, and then try to build the application around it.

Starting with the database model, however, locks you in early. For starters it decides that you'll be using a database, maybe even a particular brand. But an application should dictate storage, not the other way around.

Now I build production applications differently: I build the simplest thing that works, and let the architecture emerge from real constraints. It's not just an approach for this blog series, it's how I work day-to-day.

I know this isn't some kind of mind-blowing revelation, but if you've never tried it, I highly recommend it: it's allowed me to demonstrate and discuss with stakeholders early-on, and it's kept my pet projects from stalling out, because when you see something working quickly, you keep those sweet-sweet endorphins pumping instead of getting stuck in architecture decisions and losing interest.

Alright, enough with the philosophical digression, let's finally see some code 😅

Flipr 0: let's go ephemeral!

As promised, this first version is intentionally minimal, without any external dependencies such as databases or caching layers: pure business logic and a simple HTTP server. Everything lives in memory, which means it all disappears when the server restarts. Exactly how we like it for now :)

The stack

Nothing fancy, just solid, battle-tested tools that get the job done!

TypeScript for adding some sanity ontop of JavaScript
Node.js as the runtime
Express for the HTTP server
Winston for structured logging
Zod for request validation

Business logic

Let's start with the core: the Shortener class, which is where all the URL shortening logic lives, completely independent of HTTP, databases, or any infrastructure concerns. By keeping this business logic separate from transport and storage, the code stays clean and testable. As a bonus, we could reuse it in other contexts later, like a CLI tool or a different web framework.

import { validator } from './validator';

const NUMBER_OF_CODE_GENERATOR_RETRIES = 10;

type ShortRecord = {
  code: string;
  url: string;
};

export class CodeRestrictedError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'CodeRestrictedError';
  }
}

export class FailedUrlRetrievalError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'FailedUrlRetrievalError';
  }
}

export class ShortCodeNotFoundError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'ShortCodeNotFoundError';
  }
}

const lookup: { [key: string]: ShortRecord } = {};

const generateShortCode = (length: number) => {
  const chars =
    'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
  let code = '';
  for (let i = 0; i < length; i++) {
    code += chars.charAt(Math.floor(Math.random() * chars.length));
  }
  return code;
};

const exists = (code: string) => !!lookup[code];

const insert = (code: string, url: string) => {
  lookup[code] = { code, url };
};

const get = (code: string): ShortRecord => lookup[code];

const generateShortCodeWithRetry = (
  length: number,
  validate: (code: string) => boolean,
) => {
  let code = generateShortCode(length);
  let attempts = 0;
  while (attempts < NUMBER_OF_CODE_GENERATOR_RETRIES) {
    if (validate(code)) {
      return code;
    }

    code = generateShortCode(length);
    attempts++;
  }

  throw new Error('Failed to generate a unique short code');
};

type CodeBlockList = {
  reserved: Set<string>;
  offensive: Set<string>;
  protected: Set<string>;
};

export type ShortenerConfig = {
  shortcodeLength: number;
  codeBlockList: CodeBlockList;
};

export class Shortener {
  private readonly validate: (code: string) => boolean;

  public constructor(private readonly config: ShortenerConfig) {
    this.validate = validator(
      this.config.codeBlockList.reserved,
      this.config.codeBlockList.offensive,
      this.config.codeBlockList.protected,
    );
  }

  private test = (code: string) => this.validate(code) && !exists(code);

  public shorten = (url: string, customCode?: string): ShortRecord => {
    if (customCode && !this.test(customCode)) {
      throw new CodeRestrictedError('Custom code is restricted');
    }

    let newShortCode =
      customCode ||
      generateShortCodeWithRetry(this.config.shortcodeLength, this.test);

    insert(newShortCode, url);

    const r = get(newShortCode);
    if (!r) {
      throw new FailedUrlRetrievalError('Failed to retrieve the shortened URL');
    }

    return {
      code: r.code,
      url: r.url,
    };
  };

  public resolve = (shortCode: string): ShortRecord => {
    if (!exists(shortCode)) {
      throw new ShortCodeNotFoundError('Short code not found');
    }

    return get(shortCode);
  };
}

Let's break this down

Storage: The lookup object is our entire database. It's a simple key-value store mapping short codes to URLs. When the server restarts, everything disappears. Perfect for now.

Code Generation: The generateShortCode function creates random strings from a 62-character alphabet (a-z, A-Z, 0-9). With a default length of 7 characters, that gives us 62^7 = ~3.5 trillion possible codes. Plenty of headroom.

Collision Handling: The generateShortCodeWithRetry function tries up to 10 times to generate a valid code. "Valid" means it passes the blocklist check and doesn't already exist in our lookup. If we can't find a valid code after 10 attempts, we throw an error. In practice, with trillions of possible codes and an empty database, collisions are very unlikely.

Blocklists: the imported validator function checks three lists:

Reserved: things like api, health, admin that can be used to claim authority and exploit unsuspecting users
Offensive: self-explanatory
Protected: codes we might want to use for special purposes later, or might be exploited by confusing people, such as names of well-known social media sites

Custom codes: users can optionally provide their own short code (like flipr.io/mysite). We validate it the same way as generated codes. If it's restricted or already taken, we throw a CodeRestrictedError.

Error types: three custom error classes let the HTTP layer distinguish between different failure modes:

CodeRestrictedError: The custom code is blocked or taken (422 Unprocessable Entity)
ShortCodeNotFoundError: The code doesn't exist (404 Not Found)
FailedUrlRetrievalError: Something went wrong after insertion (500 Internal Server Error)

This separation keeps the business logic clean. The Shortener class doesn't know anything about HTTP status codes.

Wiring it up with Express

The Express server is straightforward. Here are the two main endpoints:

Shortening a URL:

app.post('/api/shorten', async (req, res) => {
  logger.info('URL shortening request', {
    type: 'shortening_try',
    originalUrl: req.body.url,
    customCode: req.body.custom_code,
  });

  try {
    const { url, custom_code } = URLRequest.parse(req.body);

    const r = shortener.shorten(url, custom_code);
    const shortUrl = `${baseUrl}/${r.code}`;

    logger.info('URL shortened successfully', {
      type: 'shortening_success',
      shortCode: r.code,
    });

    res.json({
      short_code: r.code,
      short_url: shortUrl,
      original_url: r.url,
    });
  } catch (error) {
    logger.error('API shorten error:', { type: 'shortening_error', error });

    if (error instanceof CodeRestrictedError) {
      res.status(422).json({ error: 'Custom code restricted' });
      return;
    }

    if (error instanceof FailedUrlRetrievalError) {
      res.status(500).json({ error: 'Failed to retrieve the shortened URL' });
      return;
    }

    throw error;
  }
});

We validate the request body with Zod, call shortener.shorten(), and return the result. If the shortener throws one of our custom errors, we map it to the appropriate HTTP status code.

Resolving a short code:

app.get('/:shortCode', async (req, res) => {
  logger.info('Redirection request', {
    type: 'redirect_try',
    shortCode: req.params.shortCode,
  });

  try {
    const r = shortener.resolve(req.params.shortCode);

    logger.info('Redirection successful', {
      type: 'redirect_success',
      shortCode: req.params.shortCode,
      destinationUrl: r.url,
    });

    res.redirect(302, r.url);
  } catch (error) {
    logger.error('Redirect error:', { type: 'redirect_error', error });

    if (error instanceof ShortCodeNotFoundError) {
      res.status(404).send('<h1>Short URL not found</h1>');
      return;
    }

    throw error;
  }
});

This is the redirect endpoint. When someone visits flipr.io/abc123, we look up the code and send a 302 redirect to the original URL. If the code doesn't exist, we return a 404.

The rest of the Express setup is standard boilerplate: CORS headers, static file serving for a simple web UI, a health check endpoint, and Winston logging throughout. You can see the full server code in this GitHub repo.

Running it locally

Want to try Flipr yourself? The code is open source and ready to run.

Clone and install:

git clone https://github.com/edeckers/flipr-distributed-url-shortener.git
cd flipr
git checkout part-1-ephemeral
npm install

Start the server:

npm start

The server will start on http://localhost:8000. You'll see Winston logging output in your terminal.

Shorten a URL:

curl -X POST http://localhost:8000/api/shorten \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/some/very/long/url"}'

You'll get back a response like:

{
  "short_code": "aB3xY9",
  "short_url": "http://localhost:8000/aB3xY9",
  "original_url": "https://example.com/some/very/long/url"
}

Test the redirect:

Visit http://localhost:8000/aB3xY9 in your browser, or use curl:

curl -L http://localhost:8000/aB3xY9

Try a custom code:

curl -X POST http://localhost:8000/api/shorten \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "custom_code": "mysite"}'

If you have the web UI enabled, you can also visit http://localhost:3000 in your browser for a simple form interface.

What's next

In the next post, we'll containerize Flipr and create basic Kubernetes configurations using Kustomize. We'll explore how to package the application for deployment and set up the foundation for running it in a distributed environment.

The code evolves in branches on GitHub, so you can follow along commit by commit, deploy it yourself, or jump to any stage that interests you. This is designed as a learning resource for understanding distributed systems architecture, and it's fully open source under the MPL-2.0 license.

If you spot issues, have suggestions, or want to contribute, open an issue or PR on the repo. I'm building this in public as both a learning exercise and a reference implementation for self-hosting.

Wrapping it up

We started with a simple question: what's the minimum viable URL shortener? Turns out, it's about 150 lines of TypeScript. This ephemeral version won't survive a restart, and it won't scale beyond a single instance, but that's fine and intended: we've proven the concept works, and we have a solid foundation to build on.

Next part of this series, we'll dockerize the application and add a basic Kubernetes configuration. See you then!

Have you ever started a project by building the database schema first, only to realize later that your application logic didn't quite fit? Or do you prefer starting with the data model? I'd love to hear how you approach greenfield projects in the comments!

If the Dutch language doesn't scare you, and you'd like to know more about what keeps me busy aside from writing these blog posts, check my company website branie.it! Maybe we can work together on something someday :)

Stopping Bad Actors: Inside 1Password’s Security Model

Ely — Sat, 11 Oct 2025 13:16:23 +0000

This post is part of a series on my pet projects that I’ve worked on over the years and I feel would be nice to showcase. So if you like this idea, make sure to check out my Atari 2600 emulator from my previous post!

I’ve been using password managers for many years, trusting them with literally everything: from my bank accounts to my inbox; my entire digital life actually. And since you’re reading this, you probably do too.

From the moment I started using a password manager, I wondered: how does this actually work? Why is this secure, is this secure? I pieced together a pretty firm idea of how things must work under the hood. And as it turns out, I wasn’t too far off.

But there’s a difference between having a mental model and really understanding something. For me, the best way to bridge such a gap is to build it. So I created a fully 1Password-compatible TypeScript library and turned it into an interactive explainer. I'm a web developer, not a cryptographer, which means security-wise it will leave something to be desired, but the implementation works with real 1Password data, which means I must have understood something 😅

Let me walk you through the process, using the credentials of the one and only legendary actor and director Tommy Wiseau, an avid 1Password user and ambassador himself!

Photo by Kristina Flour on Unsplash

Protecting Tommy Wiseau’s scripts and your passwords

Imagine you’re the Tommy Wiseau: you’re between takes on your latest project, and you need to access your script notes. But here’s the thing: you can’t afford to have your scripts leaked. Your creative process is unique. Your dialogue is distinctive. One leak and the internet would have a field day.

Tommy Wiseau famously starred in the Stopping Bad Actors commercial for 1Password, check it out!

So, naturally, you use a password manager, 1Password in particular. But how does 1Password actually protect Tommy’s precious scripts? How does it keep his passwords secure even from 1Password themselves? Let’s find out.

Tommy knows what's up

The Journey: from curiosity to code

Tommy's passwords are stored on 1Password's servers, but they claim they can't decrypt his vault even if they wanted to. How does that work? What's stopping a rogue employee from accessing his script for "The Room 2"? (hey, one can dream)

I found my answer in 1Password's Security Design white paper. It's an excellent read and it's pretty palatable, much more so than I expected beforehand. A recommended read for sure!

But understanding theory is one thing. I wanted to implement it. Because for me, the best way to truly understand something is to build it. So I set out to create a TypeScript library that implements 1Password's security model, which is capable of decrypting actual 1Password vault data; if my implementation couldn't handle the real thing, how would I know I truly understood it?

A pleasant surprise: the Web Crypto API, SubtleCrypto in particular, handles all the heavy lifting. PBKDF2, AES-256-GCM, RSA-OAEP, it's all built into every modern browser. No external crypto libraries needed.

And so I verified it can process actual 1Password data

To verify full compatibility, I created a test account, intercepted the encrypted data using Burp Suite and the 1Password Session Analyzer plugin to strip away the custom in-transit encryption layer on top of TLS, and wrote a test that decrypts the data using my library. The test passes, because the implementation is byte-for-byte compatible with 1Password's production encryption. Pretty cool, right?

"But I don't want to look at code, just explain it to me"

Fair enough, let's step through the process of what happens when Tommy unlocks his 1Password vault.

It's important to realize that aside from the Account Password, each of the keys in the steps below is randomly generated on your device when you create your account; 1Password only ever sees their encrypted versions.

1. Account Password + Secret Key = Account Unlock Key (AUK)

Tommy's password and his Secret Key are combined on his device using PBKDF2 (650,000 iterations), plus some salts here and there, to create the AUK. Which is an intentionally expensive operation, happening once per session. It keeps brute-force attacks at bay, and his Account Password and Secret Key a secret from 1Password.

2. AUK decrypts a keyset's Symmetric Key

The AUK unlocks a fast AES-256-GCM symmetric key. This key protects Tommy's RSA private key, while also making it easy to change the Account Password or Secret Key: only the Keyset Access Key needs to be re-encrypted with the new AUK. Everything downstream stays untouched. No need to re-encrypt your entire account.

3. Symmetric Key decrypts RSA Private Key

The symmetric key unlocks Tommy's RSA private key. Together with the public key, this keypair can decrypt his vault-specific keys without exposing his Account Password.

4. RSA Keypair decrypts Vault Keys, which encrypt Tommy's Data

Each of Tommy's vaults has its own AES-256-GCM key, encrypted by his RSA public key. These vault keys finally decrypt his actual passwords and data, including those precious script notes.

Here's what this looks like in the actual, albeit simplified, response from 1Password's servers:

{
 "uuid": "rv4ge63poeyompbhty2efk5xxi",
 "encryptedBy": "mp", // mp / auk

 // Layer 2: Symmetric key (encrypted by AUK)
 "encSymKey": {
 "alg": "PBES2g-HS256",
 "data": "xKj4pR0Ws-FyikpQGSxGk...", // Encrypted symmetric key
 "p2c": 650000 // PBKDF2 iterations

// ...

 },

 // Layer 3: RSA private key (encrypted by symmetric key)
 "encPriKey": {
 "data": "UN1mx3kJh_Qeqdyt-7Jvq...", // Encrypted private key
 "kid": "rv4ge63poeyompbhty2efk5xxi",

 // ...

 },

 // Layer 3: RSA public key (unencrypted)
 "pubKey": {
 "alg": "RSA-OAEP",
 "n": "rwVd9EM4bEwLAI4QWzJhq...",

 // ...

 }
}

Why four layers?

PBKDF2 is slow by design which adds protection against brute force
Symmetric crypto is fast, perfect for protecting the larger RSA private key
RSA enables sharing: vaults can be shared without sending Vault Passwords in plaintext or revealing your Account Password
Per-vault keys mean compromising one vault doesn't compromise others -** Rolling Account Credentials is simple** only the Keyset Access Key needs to be re-encrypted with the new AUK

You right now, probably. My name is not Mark though

Try It Yourself

Want to see this encryption chain in action? Head over to my interactive 1Password explainer. You'll see each layer of the encryption process unfold step by step.

That's Encryption, Baby!

Building this TypeScript implementation helped me understand what the 1Password Security Model looks like and why each layer exists. PBKDF2 slows down attackers and hides your password an secret key from 1Password. Symmetric crypto protects your private key efficiently. RSA enables secure sharing. Per-vault keys contain breaches.

Seeing how these pieces fit together and getting it to work with real 1Password data, turned abstract concepts into some pretty thorough understanding.

Still from "The Room" by Tommy Wiseau

If you're curious about the implementation details or want to integrate 1Password vault decryption into your own projects, the full TypeScript library is available at https://github.com/edeckers/lib1password-unofficial. It's fully compatible with real 1Password data, just don't use it in production, and obviously don't trust a library by some internet stranger like myself with your actual credentials and secrets.

For a deeper dive into 1Password's security model, particularly how it works in local client applications, David Schuetz's deep dive series is an excellent resource. Fun fact: I found his series because I encountered the string "Obfuscation Does Not Provide Security But It Doesn't Hurt" (pretty funny, I think) in the source of the 1Password site, and Googling it, his site was the only hit. He touches on it briefly :)

Did this post spark your curiosity about cryptography or password security? Are you working on similar projects, or do you have questions about the implementation? Let me know in the comments!

If the Dutch language doesn't scare you, and you'd like to know more about what keeps me busy aside from my pet projects, check my company website branie.it! Maybe we can work together on something someday :)