Developing MCP Servers in Python: From Empty Repo to the First Tool

## Why a dedicated MCP server?

Please provide the text you would like me to translate. So far I can only see the word "Setup" — could you share the full text?

pip install fastmcp
# or with uv (recommended)
uv add fastmcp

uv add fastmcp httpx

(This is a command/code snippet and does not require translation, as it is a technical instruction that remains the same in all languages.)

Stage 1: stdio Transport (Claude Code Local)

Hello World

Here is the translation of the text into English:

# server.py
from fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
def hello(name: str) -> str:
    """Say hello to someone."""
    return f"Hello, {name}!"

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

**Note:** The text you provided is a Python code snippet. Since it is source code, it does not require translation, as programming languages are universal and language-independent. The only translatable part would be the docstring `"""Say hello to someone."""`, which is already written in English. Therefore, the code remains unchanged.

Integration in Claude Code

Here is the translation of the text into English:

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

**Explanation of changes:**
- `"pfad"` (German for "path") → `"path"`
- `"absoluter"` (German for "absolute") → `"absolute"`
- `"zu"` (German for "to") → `"to"`

All other elements (JSON structure, keys, and values) remained the same, as they are technical terms or code-specific identifiers that do not require translation.

Here is the translation of the text into English:

{
  "mcpServers": {
    "my-server": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/server.py"]
    }
  }
}

**Note:** This is a JSON configuration snippet. The only part that required translation was the path placeholder `/absoluter/pfad/zu/server.py`, which translates to `/absolute/path/to/server.py` in English. All other elements (keys, commands, and values) are technical terms that remain unchanged.

Real tool with parameter validation

Here is the translated text:

from fastmcp import FastMCP
from pydantic import Field
from typing import Optional
import httpx

mcp = FastMCP("devmaker")

@mcp.tool()
async def get_articles(
    limit: int = Field(default=10, ge=1, le=100, description="Number of articles"),
    topic: Optional[str] = Field(default=None, description="Topic slug, e.g. 'linux'")
) -> str:
    """Retrieve articles from the CMS. Returns title, ID and URL."""
    params = {"limit": limit}
    if topic:
        params["topic"] = topic
    async with httpx.AsyncClient() as client:
        resp = await client.get("http://localhost:8000/api/articles/", params=params)
        resp.raise_for_status()
        data = resp.json()
    lines = [f"- [{a['title']}]({a['url']}) (ID {a['id']})" for a in data["results"]]
    return "\n".join(lines) or "No articles found."

**Changes made:**
- `"Anzahl Artikel"` → `"Number of articles"`
- `"Topic-Slug, z.B. 'linux'"` → `"Topic slug, e.g. 'linux'"`
- `"""Artikel aus dem CMS abrufen. Gibt Titel, ID und URL zurück."""` → `"""Retrieve articles from the CMS. Returns title, ID and URL."""`
- `"Keine Artikel gefunden."` → `"No articles found."`

**Error Handling**

Here is the translated text:

@mcp.tool()
async def publish_article(page_id: int) -> str:
    """Publish article. Returns URL or error message."""
    try:
        async with httpx.AsyncClient() as client:
            resp = await client.post(f"http://localhost:8000/api/pages/{page_id}/publish/")
            resp.raise_for_status()
            return f"Published: {resp.json()['url']}"
    except httpx.HTTPStatusError as e:
        return f"Error {e.response.status_code}: {e.response.text}"

Stage 2: HTTP/SSE Transport (Remote, Production)

When HTTP/SSE?

Here are a few translation options depending on the context: **Technical/General:** "Switch server to HTTP/SSE" **or** "Convert server to HTTP/SSE" **or** "Migrate server to HTTP/SSE" The most natural and commonly used translation in a technical context would be: **"Switch server to HTTP/SSE"**

Here is the translation of the text into English:

# server.py
from fastmcp import FastMCP
import uvicorn

mcp = FastMCP("devmaker", stateless_http=True)

# ... Tool definitions as before ...

if __name__ == "__main__":
    uvicorn.run(mcp.http_app(), host="0.0.0.0", port=8080)

**Note:** The text is a Python code snippet. The only translatable part was the comment `# ... Tool-Definitionen wie bisher ...` (German), which was translated to `# ... Tool definitions as before ...`. All other parts of the code remain unchanged, as they are programming syntax and not natural language.

Docker Compose

The text you provided is not a natural language text that requires translation — it is a **Docker Compose configuration file (YAML format)**. It is already written in a technical/universal format that is language-independent.

However, here is an **explanation in English** of what this configuration does:

---

**Services:**
- **mcp-server:**
  - **build:** Builds the Docker image from the current directory (`.`)
  - **ports:** Maps port `8080` on the host to port `8080` inside the container
  - **environment:** Sets the following environment variables inside the container:
    - `API_BASE_URL` – taken from the host's environment variable `${API_BASE_URL}`
    - `API_TOKEN` – taken from the host's environment variable `${API_TOKEN}`
  - **restart:** The container will automatically restart unless it is explicitly stopped

---

If you meant a **different type of text**, please let me know and I'll be happy to help! 😊

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY server.py .
CMD ["python", "server.py"]

This text is a **Dockerfile** — a technical configuration file used to build a Docker container image. It contains no natural language to translate, as it consists entirely of **Docker instructions and commands** that are language-independent and must remain exactly as written to function correctly.

The content is identical in any language context.

Claude Code with Remote Server

Here is the translated text:

{
  "mcpServers": {
    "devmaker-remote": {
      "type": "http",
      "url": "http://my-server.internal:8080/mcp"
    }
  }
}

**Note:** This is a JSON configuration snippet. The only translatable part was the German hostname `mein-server.intern` (meaning "my server, internal/intranet"), which was translated to the English equivalent `my-server.internal`. All other elements (keys, values, structure) are technical identifiers and remain unchanged.

The text you provided is a **JSON configuration snippet** (not natural language), so it doesn't require translation — it is already in a language-neutral, technical format used in programming/configuration files.

However, here is the text reproduced clearly and correctly formatted:

```json
{
  "mcpServers": {
    "devmaker-remote": {
      "type": "http",
      "url": "https://mcp.devmaker.net/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_TOKEN}"
      }
    }
  }
}
```

> **Note:** This is a JSON configuration for an MCP (Model Context Protocol) server called `"devmaker-remote"`, which connects via HTTP to `https://mcp.devmaker.net/mcp` using a Bearer token for authorization. No translation is needed, as JSON is a universal data format.

Resources (Resources)

Here is the translated text:

import json

@mcp.resource("config://server-info")
def server_info() -> str:
    """Returns server configuration and available topics."""
    return json.dumps({
        "version": "1.0",
        "topics": ["linux", "homelab", "home-automation", "electronics", "3d-printing"],
        "max_articles_per_request": 50
    }, ensure_ascii=False)

Auth: Bearer Token (This term is technical jargon and remains the same in English, as it is already an English technical term used in authentication/authorization contexts.)

Here is the translation of the text into English:

from fastmcp import FastMCP
from fastmcp.server.auth import BearerAuthProvider
import os

mcp = FastMCP("devmaker", stateless_http=True)

# FastMCP >= 2.x: auth via server parameter
mcp_with_auth = FastMCP(
    "devmaker",
    stateless_http=True,
    auth=BearerAuthProvider(token=os.environ["MCP_TOKEN"])
)

**Note:** The only change made was translating the German comment `# FastMCP >= 2.x: auth via server-Parameter` to English: `# FastMCP >= 2.x: auth via server parameter`. All code remains unchanged, as code is language-agnostic and should not be translated.

Could you please provide the text you would like me to translate? It seems only the heading "Lessons Learned" was included, but no actual text to translate. Please share the full text and I will be happy to help! --- *Note: "Lessons Learned" is already in English. If this was the complete text to be translated, then no translation is needed, as it is already in the target language.*

Here is the translation of the text into English:

if __name__ == "__main__":
    import sys
    if "--http" in sys.argv:
        import uvicorn
        uvicorn.run(mcp.http_app(), host="0.0.0.0", port=8080)
    else:
        mcp.run()  # stdio

**Note:** This text is a Python code snippet and does not require translation, as programming languages are universal and not language-specific. The code is already in English (as programming syntax is based on English keywords). The comment `# stdio` remains unchanged as it is a technical term.

If there were any German comments or strings within the code, those would be translated. In this case, the code is identical in both the "original" and "translated" versions.

Conclusion