DEV Community: Marek Cziba

Building a 16-Server MCP Monorepo in 48 Hours

Marek Cziba — Wed, 30 Sep 2026 08:19:15 +0000

Sixteen MCP servers. One repository. Two days. 197 tests, 65 tools, and a CI pipeline that fails loudly the moment any single server breaks.

This is the story of how the mcp-servers monorepo came together â€” and why I deliberately chose many small servers over one big framework.

Why 16 small servers instead of one

The default instinct when building MCP tooling is to create a monolith: one server, a giant tool namespace, dozens of parameters. In practice that hurts in three ways:

Context bloat. Every tool a server exposes is tokens an LLM pays for on every turn. A client that connects to a server advertising 65 tools burns context even if you only need sha256.
All-or-nothing trust. Nobody wants to grant an agent access to "the everything server." hash-checksum-mcp is obviously harmless; a monolith is not.
All-or-nothing installs. uvx password-generator-mcp starts in milliseconds. A framework with 40 dependencies does not.

So each server does exactly one job: hashing, base64, diffs, RSS reading, YouTube transcripts, SEO checks, unit conversion, and so on. The count of 16 is not a goal â€” it's just where "one tool family per server" ended up.

The repository layout

mcp-servers/
â”œâ”€â”€ pyproject.toml          # workspace root: shared deps + ruff + pytest config
â”œâ”€â”€ uv.lock                 # one lockfile for everything
â”œâ”€â”€ .github/workflows/
â”‚   â”œâ”€â”€ ci.yml              # lint + test matrix + build matrix
â”‚   â””â”€â”€ publish.yml         # PyPI via Trusted Publishing (OIDC)
â””â”€â”€ servers/
    â”œâ”€â”€ hash-checksum-mcp/
    â”‚   â”œâ”€â”€ pyproject.toml        # its own package, entry point, deps
    â”‚   â”œâ”€â”€ hash_checksum_mcp/
    â”‚   â”‚   â””â”€â”€ main.py           # the MCP server
    â”‚   â”œâ”€â”€ tests/
    â”‚   â”‚   â””â”€â”€ test_hash-checksum-mcp.py
    â”‚   â”œâ”€â”€ Dockerfile
    â”‚   â””â”€â”€ README.md
    â”œâ”€â”€ regex-tester-mcp/
    â”œâ”€â”€ website-to-markdown-mcp/
    â””â”€â”€ ... (16 total)

The contract is simple: every directory under servers/ is an independently installable package, and the root is just glue.

The workspace contract

The root pyproject.toml never gets published. It exists to give every server the same dependencies, the same lint rules, and the same test configuration:

[project]
name = "mcp-servers-workspace"
dependencies = [
    "mcp>=2.0,<3",
    "httpx>=0.27.0",
    "beautifulsoup4>=4.12.0",
    # ... shared third-party libs
]

[dependency-groups]
dev = ["pytest>=8.0.0", "pytest-asyncio>=0.24.0", "ruff>=0.8.0"]

[tool.uv]
package = false   # root is not a package â€” only glue

Each server declares its own pyproject.toml with a console entry point, which is what makes uvx work:

[project]
name = "hash-checksum-mcp"
dependencies = ["mcp>=2.0,<3"]

[project.scripts]
hash-checksum-mcp = "hash_checksum_mcp.main:main"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Result: uvx hash-checksum-mcp runs with zero configuration, while uv sync at the repo root installs everything for development in one shot. One lockfile, sixteen packages.

Testing: 197 tests without a mega-suite

There is no central tests/ directory. Each server ships its own tests next to its code, and the root pytest config wires imports:

[tool.pytest.ini_options]
testpaths = ["servers"]
asyncio_mode = "auto"
pythonpath = [
    "servers/hash-checksum-mcp",
    "servers/website-to-markdown-mcp/src",
    # ... every server
]

The tests are real, not smoke tests. The hash server validates against published NIST and RFC vectors:

async def test_sha256_nist_vector() -> None:
    assert await generate_hash("abc", "sha256") == (
        "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
    )

CI then runs them as a matrix of 16 â€” one job per server â€” so a failure tells you exactly which server broke instead of burying you in one log with 400 tests.

The CI pipeline

Three jobs on every push:

lint:   uv run ruff check servers
        uv run ruff format --check servers
test:   matrix: 16 servers â†’ uv run pytest servers/<name>
build:  matrix: 16 servers â†’ python -m build per package

Plus publish.yml, triggered on GitHub release, which ships selected packages to PyPI using Trusted Publishing â€” OIDC, no API tokens stored anywhere. It defaults to dry_run: true and takes an explicit packages input, so publishing one server never risks the other fifteen.

What actually bit me

The build was fast; the fixes were the real work:

pythonpath and src layouts. Fifteen servers use flat layouts, one uses src/. Listing them individually in pythonpath was the only reliable fix â€” pytest does not care about your cleverness.
Python version drift. The mcp SDK's uuid7 helper only exists on newer Pythons. A small fallback keeps servers installable on 3.10+, which is what requires-python = ">=3.10" promises.
asyncio_mode = "auto". Forgetting this is the classic MCP testing bug: every test fails with "async def functions are not natively supported" and you waste an hour suspecting the SDK.
Encoding on Windows. Writing UTF-8 markdown without a BOM and then reading it with an ANSI codepage mangles every arrow and emoji. Read files with an explicit encoding or pay for it in production.

Distribution: the part nobody writes tutorials for

Building servers is the easy half. Getting them installed is the other half:

PyPI â€” Trusted Publisher configured, releases cut from GitHub.
Glama â€” listing live: website-to-markdown-mcp.
MCPMarket â€” submitted to the free review queue.
Smithery â€” account registered; publishing requires a hosted Streamable HTTP endpoint, which is the next milestone.
Registry rule learned the hard way: Glama allows one listing per repository. Submitting a second server from the same repo gets rejected â€” monorepo or not.

What I'd do differently

Start the CI matrix from commit number one. I wrote the servers first and retrofitted the pipeline, which meant the first green run was a small celebration rather than a continuous heartbeat. Beyond that, the shape holds: small servers, one workspace, one lockfile, one matrix.

The repo is at github.com/MarekCziba/mcp-servers â€” MIT, uvx-installable, 65 tools waiting for an agent.

Previously: MCP vs Apify vs Custom Agents: When to Use Each

MCP vs Apify vs Custom Agents: When to Use Each

Marek Cziba — Wed, 30 Sep 2026 05:57:30 +0000

MCP vs Apify vs Custom Agents: When to Use Each

By Marek Cziba — Open-source MCP Server Developer

Every team building with LLMs eventually hits the same wall: the model can reason, but it cannot do. Three solutions compete for that gap — MCP servers, Apify actors, and custom agents. They are not interchangeable. Choosing wrong costs weeks of rework; choosing right ships a working product in days.

The three options, honestly defined

MCP (Model Context Protocol) is a protocol, not a product. An MCP server exposes your tools — functions, APIs, data sources — to any MCP-compatible client (Claude Desktop, Claude Code, Cursor, and growing list of others) in a standard shape: tools, resources, prompts. You write the server once, and every client that speaks MCP can use it. The value is interoperability: one integration, many consumers.

Apify is a hosted platform of pre-built automation units called actors — mostly web scraping, data extraction, and browser automation — run and monitored in the cloud, priced per compute unit. The value is infrastructure you don't operate: proxies, browsers, scheduling, storage, and thousands of actors someone else maintains.

Custom agents are your own code: a loop that calls an LLM, executes code or API calls, checks results, and iterates. Frameworks vary, but the defining trait is that you own the control flow. The value is arbitrary complexity — multi-step workflows, business rules, state, and rollback that neither MCP nor Apify provides out of the box.

Where each one wins

MCP: you have tools, and clients are the bottleneck

MCP is the right answer when you've already built (or can build) a capability as a simple function call, and the problem is getting it into the hands of AI users across different clients.

Signals you're in this situation:

Your team uses several MCP clients and refuses to maintain one integration per client.
The capability is deterministic: convert a URL to Markdown, compute a hash, read an RSS feed, query a database. No orchestration needed — one call, one result.
You want distribution. MCP registries and directories are where AI users look for tools; a well-listed server gets installed by strangers.

Cost profile: low at runtime (your code runs wherever it runs), moderate up front (one server per capability surface). Risk: you own correctness, rate limits, and auth of whatever the server wraps.

Our 16-server monorepo is exactly this shape — each server does one thing (base64, UUID v7, regex testing, website-to-Markdown conversion) with zero infrastructure. uvx hash-checksum-mcp and it's live in any client. Nothing to host, nothing to babysit.

Apify: the hard part is the web itself

Scraping looks easy until you hit rotating IPs, headless browser farms, CAPTCHAs, and HTML that changes weekly. Apify wins when your target is the open web at scale:

You need thousands of pages, not ten.
The site fights back (bot detection, geo-blocking, login walls).
You want scheduled runs, dataset storage, and proxies without building any of it.

Cost profile: predictable per compute unit, but it scales with volume — a heavy crawl is real money. Risk: vendor dependency, and actor quality varies (community actors break when target sites change).

Custom code can scrape ten pages fine. It cannot cheaply replicate a proxy network and a browser farm.

Custom agents: when the workflow is the product

Build your own agent loop when the value is in the sequence, not the single call:

Multi-step decisions with state: "gather data → validate → reconcile → draft → require human approval → publish."
Business logic that doesn't fit anyone's API: internal rules, legacy system glue, transactional rollbacks.
Latency, cost, or compliance constraints that forbid shuffling data through third parties.

The cost profile is inverted: highest up-front, lowest marginal cost — and full control. The risk is that you also own every failure mode: retries, evaluation, prompt drift, monitoring. An agent that "works in the demo" needs engineering to survive production.

A decision flow that actually resolves

Ask these five questions in order:

Is the work a single, deterministic call? → MCP server. Stop here.
Is it primarily web scraping or browser automation at scale? → Apify actor (or your own crawler only if you have unusual compliance needs).
Does it require multi-step decisions, state, or human-in-the-loop? → custom agent.
Do different AI clients need the same capability? → whatever the engine is, expose it via MCP.
Are you about to write plumbing that Apify already sells? → buy it, wrap it.

Question 4 is the trap people miss: the engine and the interface are orthogonal. The most common production pattern we see is Apify for execution, MCP for delivery.

The hybrid: MCP server wrapping an Apify actor

This combination covers 80% of real-world deployments:

AI client (Claude, Cursor)
    │  MCP protocol
    ▼
MCP server you control          ← auth, validation, business rules
    │  API call
    ▼
Apify actor                     ← browsers, proxies, storage, scheduling

The MCP server stays thin: it validates input (critical — the LLM will eventually pass garbage), maps results into clean tool responses, and enforces your API keys. Apify does the hostile-web heavy lifting. You get MCP's interoperability and Apify's infrastructure without owning either's downside.

We use the same shape inside the monorepo: servers wrap libraries (not platforms), but the boundary logic — validate in, normalize out — is identical.

What each one costs you

	Build speed	Runtime cost	You own
MCP server	Hours–days	Your hosting only	Correctness, auth
Apify actor	Minutes (existing)	Per compute unit	Input mapping, budget
Custom agent	Days–weeks	LLM tokens + infra	Everything: retries, evals, drift
Apify + MCP hybrid	Hours	Compute + your thin server	Input validation, spend limits

Bottom line

MCP is how tools reach AI clients. If you have a capability, package it as MCP — that's distribution, not architecture.
Apify is where hard web automation already lives. Buy the crawling, don't build it.
Custom agents are for workflows where the sequence itself is your product — and you're willing to own the production engineering.

Most teams don't choose one forever. They start with the cheapest thing that works (often a hosted actor or an MCP server wrapping an existing API), and reach for a custom agent only when the workflow — not the tool — becomes the differentiator.

Source code: github.com/MarekCziba/mcp-servers — 16 MCP servers, one monorepo, full CI/CD to PyPI.

Install the flagship in one line: uvx website-to-markdown-mcp

Skills & Keywords

MCP ModelContextProtocol Apify AIAgents FastMCP Automation Scraping LLM OpenSource

Contact

LinkedIn: https://www.linkedin.com/in/marek-cziba-669521372/
GitHub: https://github.com/MarekCziba
PyPI: https://pypi.org/user/marekcziba/