aiohttp-tiny-mcp

Documentation · Repository · Issues · Releases

aiohttp-tiny-mcp turns an aiohttp service into a remote MCP server. Declare Python handlers as tools, resources, or prompts; the library exposes them over Streamable HTTP or stdio.

It is designed for services behind a load balancer. A later request from one MCP client may reach another process, so sessions and events live in backends shared by all workers. For one process, the included memory backends are used automatically.

Start here

1. Quickstart — run a server and call a tool.

2. Tools, resources, and prompts — choose what to expose.

3. How the server fits together — understand Exchange, SessionStore, and Hub before deploying more than one worker.

4. Authentication — protect a standalone endpoint or mount it in an aiohttp application that already verifies JWTs.

The library supports 2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25, and 2026-07-28 from one set of handlers. Use the compatibility table for protocol differences.

Already use the official Python SDK? Read how it compares before choosing a framework. For local benchmark methodology and results, see What it costs.

Getting started

• Quickstart
  • Install
  • Define the server
  • Run it
  • Discover and call the tool
  • Add the next feature
• Tools, resources, and prompts
  • What you declare
  • MCP and this library
  • Official Python SDK
• How the server fits together
  • The ordinary call
  • Why Store and Hub exist
  • One important lifetime rule

Writing handlers

• Tools
  • Declaring one
  • Names, titles and hints
  • What a tool may return
  • Failures are results, not errors
  • Without a decorator
  • Long calls
  • Asking the user
  • Requiring a newer revision
• Resources
  • A fixed resource
  • A template
  • What a handler may return
  • Reading one that is not there
  • Telling clients it changed
  • Cache hints
  • When a resource is the wrong shape
• Prompts
  • Declaring one
  • Returning several messages
  • Names and titles
  • Suggesting argument values
  • A prompt may ask, too
• Completion
  • What the handler is told
  • Returning more than a list
  • Filtering yourself
  • No handler at all
• Using Exchange
  • Arguments belong to the client; the exchange belongs to the server
  • What to use it for
  • Lifetime: an invocation can end before the conversation does
• Dependencies
  • An object you already have
  • A factory
  • An application key
  • An async generator
  • The exchange itself
  • What middleware decided
  • Missing providers are caught early
• Authentication
  • Where the metadata has to be served
  • JWT middleware in an existing aiohttp application
• Testing a server
  • Test the HTTP boundary
• Asking the user
  • The same call, every revision
  • What actually happens
  • Asking for data, not just agreement
  • Refusal is not failure
  • Where nobody can answer
  • Several questions
  • Carrying state between the calls
  • The client’s side
• Notifications
  • Progress
  • Logging
  • Changes to what the server offers
  • What a subscription is not
• Sessions and state
  • Values that outlive a call
  • Addressing a session
  • Writing safely
  • State between two calls
  • Lifetimes

Calling and running a server

• The client
  • Choosing a revision
  • What the constructor takes
  • Calls
  • Errors
  • Over stdio
• The console
  • Nothing to configure
  • What it shows
  • Descriptions are markdown
  • Every revision
  • Questions
  • Your own page
  • Before you mount it
  • Three files, no build
• Transports
  • Streamable HTTP
  • stdio
  • HTTP+SSE, for 2024-11-05 clients
  • Which one a client uses
• Stores and hubs
  • Choose backends for the deployment
  • On SQLite
  • On Redis
  • On PostgreSQL
  • Maintaining PostgreSQL
  • What goes where
  • The session store
  • The hub
  • Running more than one worker
  • Timeouts
• Many tenants on one server
  • Setting it
  • What it covers
  • Where the name should come from
  • What it does not do

Reference

• What it costs
  • How to read it
  • Conditions
  • Server over HTTP, per revision
  • Client over HTTP, per revision
  • Over stdio
  • What these numbers are not
• What each revision gets
  • The matrix
  • What is genuinely lost
  • What costs something
  • What it takes
  • Client compatibility
• What varies between revisions
  • The inventory
  • The three ways to ask
  • What the client declares
  • Degradation that is not a choice
• Adapters
  • Layering
  • Design goals
  • What an adapter is
  • Behavioural flags
  • The surface
  • Failure mapping
  • Argument failures are results, not errors
  • Adding a revision
• Choosing a revision
  • Why it happens first
  • The algorithm
  • The ?mcp= pin
  • Refusal
  • Superseding
  • Remembering the choice
• The normalized core
  • Operation
  • Call
  • Outcome
  • Exchange
  • Dispatcher
  • Endpoint
  • Caching
• How this is verified
  • The parametrized suite
  • Our client against our server
  • Independent implementations
  • Two stacks in four processes
  • The documentation
  • Running it
  • Not implemented
• API
  • Declaring what a server offers
  • Serving it
  • Inside a handler
  • Sessions and state
  • Events
  • On SQLite
  • Streams
  • On Redis
  • On PostgreSQL
  • Many tenants
  • Authentication
  • Clients
  • Revisions
  • The normalized core