Build Your First Endpoint

You'll build a real endpoint: text in, QR code image out. When you finish, it will be a REST API, an MCP tool, and a documented page with a Try-it button, all from one class.

You are not going to type it. You are going to describe it, then check four things. Everything below was run exactly this way before it was published.

One sentence of background, because the four checks depend on it: CLAUDE.md tells your agent exactly where an endpoint's files go and what they are called, which is why those checks are checks rather than guesses. The rest of the explanation is at the bottom of this page, once you have something running.

1. Give your agent this prompt

In the Claude Code session you opened in Open It in Claude Code:

That last line is the one people leave out. It turns a wall of output into a short list you can actually check.

Here is the real reply from the run that produced this page:

2. Check four things

Not the whole diff. These four:

from django.apps import AppConfig


class QrCodeConfig(AppConfig):
    default_auto_field = "django.db.models.BigAutoField"
    name = "apps.app_endpoints.qr_code"
    label = "endpoints_qr_code"

from __future__ import annotations

import base64
import io

import qrcode
from pydantic import BaseModel, Field

from apps.core.ctx import Ctx
from apps.core.registry import Endpoint, endpoint


@endpoint(slug="qr-code", description="Turn any text or link into a QR code image.")
class QrCode(Endpoint):
    class Input(BaseModel):
        text: str = Field(
            description="The text or link to encode.",
            min_length=1,
            max_length=1000,
        )
        size: int = Field(
            default=8,
            description="Pixel size of each QR square (2-20).",
            ge=2,
            le=20,
        )

    class Output(BaseModel):
        image_data_uri: str
        encoded_text: str

    async def run(self, inp: Input, ctx: Ctx) -> Output:
        image = qrcode.make(inp.text, box_size=inp.size)
        buffer = io.BytesIO()
        image.save(buffer, format="PNG")
        encoded = base64.b64encode(buffer.getvalue()).decode("ascii")
        return self.Output(
            image_data_uri=f"data:image/png;base64,{encoded}",
            encoded_text=inp.text,
        )

from __future__ import annotations

import asyncio
import base64

from apps.app_endpoints.qr_code.endpoints import QrCode
from apps.core.testing import call_endpoint


def test_qr_returns_png_data_uri() -> None:
    out = asyncio.run(call_endpoint(QrCode, {"text": "https://learnwithhasan.com"}))
    assert out.image_data_uri.startswith("data:image/png;base64,")
    png = base64.b64decode(out.image_data_uri.split(",", 1)[1])
    assert png[:8] == b"\x89PNG\r\n\x1a\n"

    "apps.app_endpoints.qr_code",

3. Reload the stack

.\scripts\stack-up.ps1 -Reload

(macOS / Linux: ./scripts/stack-up.sh --reload.) This rebuilds just the app services and takes about a minute; our measured run was 58 seconds.

4. Use it

Open http://localhost:8000/docs/ in your browser. Your qr-code endpoint is now in the catalog, with a full page of its own at /docs/qr-code/.

Scroll down to the Try it panel. Paste your mcpsk_... key into the API key box, put https://learnwithhasan.com in the text field, and press Send request.

The response contains image_data_uri, a string starting with data:image/png;base64,. Paste that whole string into your browser's address bar: there's your QR code. Scan it with your phone.

Or from the terminal:

Invoke-RestMethod -Uri http://127.0.0.1:8000/api/v1/qr-code -Method Post -ContentType 'application/json' -Body '{"text":"https://learnwithhasan.com"}'

Why that worked

Now that it's running, the two-sentence version of what just happened.

Your agent did not invent the shape; it looked it up. CLAUDE.md carries a 6-step endpoint authoring recipe with the file names spelled out, five worked endpoints under apps/app_endpoints/ to copy from, and a boundary marking the fourteen framework apps it must not edit. That is why "check four things" is a realistic instruction. In a repo without that file, an agent asked for "an MCP endpoint" reaches for @mcp.tool() and a fresh FastMCP() server, and you get a second server bolted next to the one you own.

One class, three surfaces, because of the decorator. @endpoint(slug="qr-code", ...) puts the class in a registry at boot. From that one entry, apps.core generates the REST route, apps.mcp_proxy registers the MCP tool, and apps.docs builds the page and the Try-it panel you just used. The Input model is what rejects bad calls before your code runs, and the Output model is what shapes the JSON that came back. You wrote none of those three surfaces, and there is no place where you could have.

That is also why the reload in step 3 is mandatory: the registry is built when the app boots, from the files inside the image.

You have now used the whole pattern

Every endpoint you add from here is these same steps: describe what you want, check four things, reload. Nothing above was specific to QR codes.

Then reload and open /docs/word-count/. That is your second endpoint, and it took one paragraph.

You described one endpoint. You got three surfaces. Next: Use It From Claude.