restmcp
One framework. MCP tools and REST endpoints, auto-registered.
Python framework for building MCP servers with a layered architecture and REST compatibility.
Annotated classes become MCP tools and HTTP endpoints: auto-registered, dependency-injected, sync/async agnostic.
Architecture
graph LR
LLM["🤖 LLM / Client"] -->|"HTTP or MCP"| EP["Endpoint"]
EP --> SV["Service"]
SV --> RP["Repository"]
RP --> DS["DataSource"]
DS --> EX[("External\nAPI / DB")]
style EP fill:#4f46e5,color:#fff,stroke:none
style SV fill:#7c3aed,color:#fff,stroke:none
style RP fill:#9333ea,color:#fff,stroke:none
style DS fill:#a855f7,color:#fff,stroke:none
Each layer knows only the layer directly below it. Every class name is suffix-enforced at import time: a typo raises TypeError before the server starts.
Installation
pip install restmcp
Quick start
restmcp new my-server
cd my-server
pip install -e .
python main.py
Generated structure:
my-server/
├── datasources/ # external connections (APIs, databases)
├── entities/ # domain models (Pydantic)
├── repositories/ # data access layer
├── services/ # business logic
├── utils/ # internal helpers
├── endpoints/ # endpoint definitions (auto-discovered)
├── main.py
└── pyproject.toml
Changelog
Release-by-release record in CHANGELOG.md — every behavior/API change lands there under Unreleased and ships with the version bump.
Breaking changes in 0.2.0
Definition errors now fail at registration (import time) instead of per-request, always naming the endpoint class or tool:
- Parameter names starting with
_ormodel_(or that are not valid Python identifiers) are rejected — pydantic silently dropped or refused them before. - A declared
defaultthat does not match its declared type is rejected (defaults are now validated and coerced at registration). - The callback signature must accept every declared property (defaults included) — on 0.1.x this worked on REST and broke only on MCP.
Runtime changes: unknown query-string parameters are now ignored (previously HTTP 400); REST and MCP now validate identically via one shared pydantic model, so HTTP 400 messages are pydantic-style (e.g. "Extra inputs are not permitted"); explicit JSON null is accepted only when the property's default is null; pydantic-lax boolean inputs (1/0, "on"/"off", "yes"/"no") are accepted.
How it works
sequenceDiagram
participant C as Client / LLM
participant E as Endpoint
participant S as Service
participant R as Repository
participant D as DataSource
C->>E: POST /api/get-product {"product_id": "1"}
E->>S: service.execute(product_id="1")
S->>R: repo.get(product_id="1")
R->>D: data_source.fetch("1")
D-->>R: raw dict
R-->>S: ProductEntity
S-->>E: result dict
E-->>C: {"tool": "get_product", "result": {...}, "success": true}
Base classes
DataSource
Abstracts the connection to an external data source (REST API, database, file).
Rule: class name must end with DataSource.
import httpx
from restmcp import DataSource
class ProductApiDataSource(DataSource):
base_url = "https://api.example.com"
async def fetch(self, product_id: str) -> dict:
async with httpx.AsyncClient() as client:
r = await client.get(f"{self.base_url}/products/{product_id}")
r.raise_for_status()
return r.json()
Entity
Structured domain data backed by Pydantic. Automatic type validation.
Rule: class name must end with Entity.
from restmcp import Entity
class ProductEntity(Entity):
id: str
name: str
price: float
Repository
Fetches data via a DataSource and returns Entity objects. One source, one data type.
Rules: name ends with Repository; must declare data_source as class attribute; must implement get().
from restmcp import Repository
from datasources.product_api import ProductApiDataSource
from entities.product import ProductEntity
class ProductRepository(Repository):
data_source = ProductApiDataSource()
async def get(self, product_id: str) -> ProductEntity:
raw = await self.data_source.fetch(product_id)
return ProductEntity(**raw)
Dependency injection:
repo = ProductRepository() # uses real DataSource
repo = ProductRepository(data_source=MockDataSource()) # injects mock for tests
Repository.__init__ uses copy.copy() of the class attribute: instances are always isolated.
Service
Orchestrates business logic. Where joins, transformations, and multi-source rules live.
Rules: name ends with Service; must declare at least one Repository as class attribute.
from restmcp import Service
from repositories.product import ProductRepository
class GetProductService(Service):
repo = ProductRepository()
async def execute(self, product_id: str) -> dict:
product = await self.repo.get(product_id=product_id)
return product.model_dump()
Dependency injection:
svc = GetProductService() # production
svc = GetProductService(repo=MockRepository()) # test
Repository class attributes are auto-discovered via MRO and isolated per instance.
Endpoint
HTTP + MCP route. Auto-registers on class definition: no manual wiring needed.
Rules: name ends with Endpoint; must declare url, method, and callback. mcp_definition is inferred from the callback when omitted.
from typing import Annotated
from restmcp import Endpoint
from services.product import GetProductService
class GetProductEndpoint(Endpoint):
url = "/api/get-product"
method = "POST"
async def callback(self, product_id: Annotated[str, "Product ID"]) -> dict:
"""Get a product by ID.
Returns: the product object (id, name, price, currency).
"""
return await GetProductService().execute(product_id)
The MCP tool name (get_product), description (the full callback docstring),
and parameter schema (types + Annotated text) are inferred from the callback.
The callback docstring must include a Returns: section — the MCP client only
ever sees the tool description, so an inferred tool is required to spell out what it
returns there (the Portuguese Retorna:/Retorno: are also accepted). Defining an
inferred endpoint without one raises a TypeError at class-definition time.
Set mcp_definition explicitly only when you need to override the inferred schema;
the Returns: requirement does not apply to hand-written definitions.
Defining the class is enough. The route is registered on the Server singleton the moment Python processes the class body.
Choosing the transport (0.3.0+):
class RejectEndpoint(Endpoint):
expose = "rest" # "rest" | "mcp" | "both" (default)
...
"rest" serves the HTTP route but keeps the tool out of the MCP server and
the /mcp/tools catalog — an agent never even sees it (write endpoints an LLM
must not call, binary downloads that make no sense as tools). "mcp" registers
the tool with no public HTTP route (agent-only tools). Invalid values raise at
class definition. The filter is one place (Server.mcp_handlers), so the
catalog and the MCP server cannot disagree.
OpenAPI schemas (0.3.0/0.4.0+): /openapi.json documents every operation
from the same mcp_definition the MCP side publishes — REST and MCP cannot
drift:
- Request (0.3.0):
requestBodyforPOST/PUT/PATCH, queryparametersotherwise, plusoperationIdanddescription.requiredmirrors validation (a property without adefault);additionalProperties: falsedocuments the extra-key rejection. - Response (0.4.0): declare
mcp_definition["returns"]as the JSON Schema of the callback's return value and the200documents the{tool, result, success}envelope withresulttyped by it (open when undeclared — the envelope alone already types the skeleton). Errors are documented once, underdefault, with the error envelope.
class GetProductEndpoint(Endpoint):
mcp_definition = {
"name": "get_product",
"description": "Get a product by ID.",
"parameters": {"properties": {"product_id": {"type": "string"}}},
"returns": {
"type": "object",
"properties": {"id": {"type": "string"}, "price": {"type": "number"}},
"required": ["id", "price"],
},
}
...
Generated clients (openapi-typescript, openapi-python-client, …) now get
full request/response types — a renamed response field becomes a codegen diff
instead of silently empty UI data.
Success status code (0.6.0+): the HTTP code of the success envelope is a declaration, and the same declaration feeds the response and the OpenAPI document — they cannot disagree:
class StartRunEndpoint(Endpoint):
success_code = 202 # "accepted, poll for the outcome" — default 200
...
2xx only, validated at class definition; 204 is rejected (No Content forbids
a body, the envelope always has one). Errors ignore it — their code comes from
the exception class (RestMCPException.status_code), so the full picture is:
error code = exception type, success code = endpoint declaration.
Raw responses (0.6.0+): the FastAPI escape hatch, for responses that do not fit the envelope (file downloads, redirects, conditional codes, custom headers). Three locks:
class ExportCsvEndpoint(Endpoint):
expose = "rest" # lock 1: no MCP side — required, or import fails
raw_response = True # lock 2: opt-in, never inferred from the return type
...
def callback(self, device_id):
return PlainTextResponse(csv, media_type="text/csv",
headers={"content-disposition": "attachment"})
- Requires
expose = "rest"— a raw HTTP response has no MCP representation, so the tool must not exist on that side. - Opt-in declared — a callback returning a
Responsewithout the flag is a programming error (500, pointed message in the log), never a silent passthrough; declared but returning plain data errors the same way. - Success only — exceptions raised in a raw endpoint still produce the standard error envelope with the exception's status code: clients keep one error format everywhere. Auth, scopes, body limits and parameter validation also apply unchanged — the hatch is about the response, not the pipeline.
In OpenAPI a raw operation promises nothing it cannot keep: no success
envelope, one honest default describing that code, headers and body belong
to the endpoint.
Disabling an endpoint:
class GetProductEndpoint(Endpoint):
disabled = True # skips auto-registration; can still be instantiated manually
...
Abstract base classes (missing any required attribute) are never auto-registered:
class BaseAuthEndpoint(Endpoint):
method = "POST"
def callback(self, **kwargs): ...
# ↑ not registered: url is missing
class GetUserEndpoint(BaseAuthEndpoint):
url = "/api/get-user"
def callback(self, user_id: str) -> dict: ...
# ↑ registered automatically: url, method, and callback all present
Sync and async callbacks are both supported: restmcp detects and handles either:
# sync: runs in a thread pool, does not block the event loop
def callback(self, product_id: str) -> dict:
return requests.get(f"https://api.example.com/products/{product_id}").json()
# async: awaited directly; use asyncio.gather for parallel I/O
async def callback(self, product_id: str) -> dict:
async with httpx.AsyncClient() as client:
r = await client.get(f"https://api.example.com/products/{product_id}")
return r.json()
The contract (identical for REST and MCP):
- A sync callback runs in a threadpool, so blocking work — a synchronous DB
driver,
requests, file I/O — never stalls the event loop. Writing yourRepository/DataSourcesynchronously is the simple, correct default. - An async callback is awaited directly. Inside it, keep the I/O async
(
httpx, an async DB driver): calling blocking code from an async callback does stall the loop, because it is not moved to a thread.
Rule of thumb: sync all the way down, or async all the way down — don't put
blocking calls inside an async def callback.
Response format:
{ "tool": "get_product", "result": { ... }, "success": true }
{ "tool": "get_product", "error": "not found", "error_type": "NotFoundError", "success": false }
Server
Singleton serving REST (FastAPI/uvicorn) and the MCP protocol (FastMCP) from one
codebase. The recommended entry point is asgi_app(), which mounts both:
import uvicorn
from restmcp import Server, autodiscover
autodiscover("endpoints") # imports every endpoint module so each one registers
app = Server.get_instance().asgi_app() # REST at "/", MCP at "/mcp-protocol/"
if __name__ == "__main__":
uvicorn.run(app, host="0.0.0.0", port=8000)
# REST only (no MCP), if that is all you need:
Server.get_instance().start(host="0.0.0.0", port=5000)
# The raw FastMCP instance (escape hatch):
mcp = Server.get_instance().get_mcp()
Built-in routes:
| Route | Method | Auth required |
|---|---|---|
/health |
GET | No |
/mcp/tools |
GET | No |
| your endpoints | POST | Yes (if AUTH_API_KEY is set) |
Production checklist
- Running REST + MCP together: use
app = server.asgi_app()— it mounts both and wires the FastMCP lifespan. Do not callserver.app.mount(...)directly: it raises "Task group is not initialized" on the first MCP request. MCP is served at themcp_pathyou pass (default/mcp-protocol/, trailing slash); REST stays at/. - Auth: set
AUTH_API_KEY(Bearer).asgi_app()protects REST and the mounted MCP;/healthand/mcp/toolsremain public. Multiple keys: comma-separated. - Serialization: callback return values are serialized with
jsonable_encoder—datetime→ ISO 8601,Decimal→ string, Pydantic models → dict, automatically. Override per-entity viaserialize(). - Typed parameters: a parameter declared as
{"type": "string", "format": "date-time"}arrives in the callback as a string — coerce todatetimeif needed. - Caching: wrap an expensive Service method with
@cached_method(ttl=seconds, maxsize=128)— the cache key is built from the arguments (viarepr), so it works even withlist/dictargs. The store is bounded (maxsize) and self-purging (TTL), so it is safe in long-running processes. Cache plain-data arguments, not rich objects. - Folders vs suffixes: only class suffixes are enforced (
*Entity,*Repository,*Service,*Endpoint,*DataSource); folder names are free. - Dependencies:
fastmcp3.x is recommended (this package requiresfastmcp>=2.0; upgrade to 3.x for full Streamable HTTP support). Installing fastmcp also pulls instarlette.
A complete, runnable server using all of the above lives in examples/telemetry/ — no database required.
Exceptions
Raised inside callback: caught by Endpoint and converted to HTTP responses automatically.
from restmcp import ValidationError, NotFoundError
raise ValidationError("product_id is required") # → HTTP 400
raise NotFoundError("Product not found") # → HTTP 404
graph TD
RestMCPException --> ValidationError["ValidationError (400)"]
RestMCPException --> NotFoundError["NotFoundError (404)"]
Testing with injection
from restmcp import DataSource
from repositories.product import ProductRepository
from services.product import GetProductService
class FakeProductApiDataSource(DataSource):
async def fetch(self, product_id: str) -> dict:
return {"id": product_id, "name": "Test Widget", "price": 1.99}
def test_get_product():
svc = GetProductService(repo=ProductRepository(data_source=FakeProductApiDataSource()))
result = svc.execute(product_id="1")
assert result["name"] == "Test Widget"
Key identity and scopes (0.5.0+)
AUTH_API_KEY entries accept an optional name:key:scope form alongside the
plain key form (which keeps full scope):
export AUTH_API_KEY="painel:sk_abc:read, campo:sk_def:read+write, sk_legacy"
The matched principal {"name", "scopes"} is published as request.state.auth
and via the restmcp.auth.current_auth contextvar (visible inside sync
callbacks too). Declare required_scope = "write" on an Endpoint to get a
403 before the callback when the key lacks it (REST path; on the MCP side,
hide sensitive tools with expose = "rest"). The secret itself never
propagates.
Environment variables
| Variable | Default | Description |
|---|---|---|
AUTH_API_KEY |
(disabled) | Bearer token. Multiple keys supported comma-separated. |
CORS_ORIGINS |
(unset — deny) | Allowed origins, comma-separated. Absent or empty denies cross-origin (0.5.0; was *) — set '*' explicitly to allow any. A warning is logged when denied by omission. |
MAX_BODY_BYTES |
1048576 |
Global request-body ceiling (bytes); bodies over it get 413. Override per endpoint with the max_body_bytes class attribute. |
LOG_LEVEL |
INFO |
Log level: DEBUG, INFO, WARNING, ERROR. |
Naming conventions
All base classes enforce a suffix. Violating it raises TypeError at import time: before the server starts.
| Base class | Required suffix | Example |
|---|---|---|
DataSource |
*DataSource |
ProductApiDataSource |
Entity |
*Entity |
ProductEntity |
Repository |
*Repository |
ProductRepository |
Service |
*Service |
GetProductService |
Endpoint |
*Endpoint |
GetProductEndpoint |
Dependencies
fastapi >= 0.100
uvicorn >= 0.20
fastmcp >= 2.0
pydantic >= 2.0
click >= 8.0
Author
Jorge Henrique Moreira Santana
Electrical Engineer, Postgraduate in Artificial Intelligence
LinkedIn · jorge.henrique.moreira.santana@gmail.com
License
Metadata
Release files for restmcp 0.6.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| restmcp-0.6.1.tar.gz | 92.9 kB | With provenance | Details for restmcp-0.6.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| restmcp-0.6.1-py3-none-any.whl | Python 3 | none | any | Details for restmcp-0.6.1-py3-none-any.whl |
Total release size: 130.8 kB
Release files / restmcp-0.6.1.tar.gz
| Download URL | restmcp-0.6.1.tar.gz |
|---|---|
| Size | 92.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9ba4213358146ab6f95d2b242f5ee189fd4565c403098e3c6c7dfeaed7b4c553
|
|
BLAKE2b-256 checksum How to use checksums |
254c8352cd3d4b850e319f7cfc73aad6c53ed74d159527e35df4bcc01a4b7509
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 8, 2026.
Transparency logRelease files / restmcp-0.6.1-py3-none-any.whl
| Download URL | restmcp-0.6.1-py3-none-any.whl |
|---|---|
| Size | 37.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2c061cb44caed2a73841992499413ebce162adb79cbdac703f6f44a0fe228305
|
|
BLAKE2b-256 checksum How to use checksums |
4db75fcfc83a872c704d4af0625caa3de9e08678911be20e119be07f842fc87d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 8, 2026.
Transparency logSecurity for restmcp 0.6.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for restmcp-0.6.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 8, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.