# Mcpatom

> A minimal MCP server SDK in one stdlib-only Python module

- **Type:** MCP server
- **Install:** `agentstack add mcp-physcat-mcpatom`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [physcat](https://agentstack.voostack.com/s/physcat)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [physcat](https://github.com/physcat)
- **Source:** https://github.com/physcat/mcpatom

## Install

```sh
agentstack add mcp-physcat-mcpatom
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mcpatom

A minimal Python [MCP](https://modelcontextprotocol.io) Server SDK.

From Greek *atomos*: indivisible. The whole library is a single file,
`mcpatom.py`, consumable two ways:

- **Copy the file** into your project. No dependency, no lockfile entry.
- **Install the package**: `pip install mcpatom` - the file itself is
  the installed module.

## Scope

- Tools, resources, and prompts, over stdio or streamable HTTP.
- Protocol versions `2025-06-18` and `2025-11-25`.
- stdlib-only Python >= 3.10, no dependencies, ever.

Everything else (sampling, elicitation, subscriptions, auth, etc.) is deliberately omitted.

## Usage

```python
from mcpatom import Server

srv = Server("my-server")

@srv.tool
def greet(name: str, excited: bool = False) -> str:
    """Return a greeting for the given name."""
    return f"Hello, {name}{'!' if excited else '.'}"

@srv.resource("data://motd")
def motd() -> str:
    """Message of the day."""
    return "Be indivisible."

@srv.prompt
def haiku(topic: str) -> str:
    """Ask for a haiku."""
    return f"Write a haiku about {topic}."

srv.serve_stdio()
```

For streamable HTTP instead of stdio, end with:

```python
srv.serve_http(8388)  # http://127.0.0.1:8388/mcp
```

`serve_http` binds to loopback and rejects DNS-rebinding requests;
`host="0.0.0.0"` widens the bind and switches those checks off.

More runnable servers in [examples/](examples/).

## Schemas and return types

Each function's name, docstring, and annotations become the tool's name,
description, and schema; `@srv.tool(name=, description=, input_schema=,
output_schema=)` override generation, and `extra=` merges raw fields into
the listing. `Server()` also takes `version=` and `instructions=`.
Parameters may be annotated with any of these:
- `str`
- `int`
- `float`
- `bool`
- `list[X]` (or bare `list`)
- `Literal[...]`
- `TypedDict`
- `X | None` of any of the above

`Annotated[X, "text"]` adds a description the model sees. A parameter's
default is published in the schema when it is JSON-representable; a `None`
default is omitted unless `null` is a selectable `Literal` value.

A tool may return:

- `str` - one text block
- `dict` - JSON text plus `structuredContent`; a `TypedDict` return
  annotation publishes the matching `outputSchema`
- `Image(data, mime_type)` / `Audio(data, mime_type)` - one binary
  block (raw bytes in, base64 on the wire)
- a tuple - one block per item: `str` text, `Image`/`Audio` media, a
  dict whose `"type"` names a spec block type verbatim (e.g.
  `resource_link`)
- `None` - empty content; any other JSON value - text

Raising is the error API: any exception becomes `isError` content the
model can read and correct.

Resources return `str` (text) or `bytes` (base64 blob).

Prompts take only `str` arguments and return a `str` user message, or a
list of message dicts passed through verbatim.

## Wiring it up

```sh
claude mcp add my-server -- /abs/path/.venv/bin/python /abs/path/server.py
```

or in any `mcpServers` config:

```json
{"mcpServers": {"my-server": {"command": "/abs/path/.venv/bin/python", "args": ["/abs/path/server.py"]}}}
```

Smoke test without a client:

```sh
echo '{"jsonrpc":"2.0","id":1,"method":"ping"}' | python server.py
# {"jsonrpc":"2.0","id":1,"result":{}}
```

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [physcat](https://github.com/physcat)
- **Source:** [physcat/mcpatom](https://github.com/physcat/mcpatom)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-physcat-mcpatom
- Seller: https://agentstack.voostack.com/s/physcat
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.