Metadata-Version: 2.4
Name: aiohttp-mcp-server
Version: 0.1.0
Summary: MCP (Model Context Protocol) server support for aiohttp
License-Expression: Apache-2.0
Project-URL: Documentation, https://aiohttp-mcp-server.readthedocs.io
Project-URL: Repository, https://github.com/aio-libs/aiohttp-mcp-server
Project-URL: Issues, https://github.com/aio-libs/aiohttp-mcp-server/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: aiohttp
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: aiohttp>=3.10
Requires-Dist: aiohttp-sse>=3
Requires-Dist: pydantic>=2.11
Requires-Dist: typing_extensions>=4.9; python_version < "3.13"
Provides-Extra: jwt
Requires-Dist: PyJWT[crypto]>=2.8; extra == "jwt"
Dynamic: license-file

aiohttp-mcp-server
==================

A framework to easily make production-grade `MCP <https://modelcontextprotocol.io/>`_
servers for AI agents.

Installation
------------

.. code-block:: bash

    pip install aiohttp-mcp-server

Usage
-----

.. code-block:: python

    import aiohttp_mcp_server as mcp
    from aiohttp import web

    async def get_weather(location: str) -> str:
        """Get current weather information for a location."""
        return f"Sunny in {location}."

    app = web.Application()
    mcp.setup(app, tools=mcp.ToolRegistry(get_weather))
    web.run_app(app, handler_cancellation=True)

This serves the MCP endpoint at ``/mcp``. This can be added to any existing
aiohttp web application, or used as a standalone one as above.

Note that it is especially recommended to enable handler cancellation for MCP servers,
but you should read the documentation first to understand the impact it has on your
handlers: https://docs.aiohttp.org/en/stable/web_advanced.html#web-handler-cancellation

Remote servers and auth
-----------------------

A server exposed on the internet needs two additions: the domain added to
``allowed_origins``, and an authorization configuration. MCP uses OAuth 2.1, and
aiohttp-mcp-server ships everything needed for it out of the box (including an
authorization server) so a complete, working deployment is:

.. code-block:: python

    import os
    import secrets

    import aiohttp_mcp_server as mcp
    from aiohttp import web

    async def check_credentials(username: str, password: str, request: web.Request) -> bool:
        return username == "admin" and secrets.compare_digest(
            password, os.environ["MCP_PASSWORD"]
        )

    app = web.Application()
    mcp.setup(
        app,
        allowed_origins=("mcp.server.example",),
        authorization=mcp.LocalAuthorization(
            check_credentials,
            resource="https://mcp.server.example",
            secret=bytes.fromhex(os.environ["MCP_TOKEN_KEY"]),
        ),
    )
    web.run_app(app, handler_cancellation=True)

``LocalAuthorization`` makes the application its own OAuth 2.1 authorization
server, with the credential check as the only deployment-specific part. Larger
deployments with multiple users should use ``Authorization`` to connect to an
established OAuth server instead.
