AWS Labs Core Model Context Protocol Server

Common errors

• OSError: [Errno 98] Address already in use

  cause The network port specified for the MCP server is already being used by another process or application.
  fix Stop the process using the port, or configure the MCP server to listen on a different, available port (e.g., 8081, 9000). For the quickstart, modify `port = 8080` to another value.

• ModuleNotFoundError: No module named 'awslabs_core_mcp_server'

  cause The `awslabs-core-mcp-server` package has not been installed in the active Python environment.
  fix Install the package using pip: `pip install awslabs-core-mcp-server`.

• websockets.exceptions.ConnectionClosedOK: no close frame received

  cause This error typically occurs when a client disconnects unexpectedly or without sending a proper WebSocket close frame, or if there's a network interruption.
  fix Verify client-side WebSocket implementation for proper connection management and graceful closures. Check network stability and firewall configurations. For server-side, it often indicates a client-side issue rather than a server bug.

Warnings

• gotcha The server heavily relies on Python's `asyncio` library. Users unfamiliar with asynchronous programming in Python might face challenges with correctly integrating, starting, and gracefully shutting down the server within their applications.
  Fix: Ensure a proper `asyncio` event loop is running and managed. Use `asyncio.run()` for simple scripts, and handle `KeyboardInterrupt` for graceful shutdown. For complex applications, integrate the server within an existing event loop.
• gotcha By default, the quickstart and CLI examples often use a common port (e.g., 8080). This can lead to port contention if another application is already using that port, preventing the MCP server from starting.
  Fix: Always specify a port that is known to be free for your environment. In programmatic setup, change the `port` variable. If using the CLI, provide `--port <new_port>`.

Install

• pip install awslabs-core-mcp-server Install stable version

Imports

• InMemoryModelContextProtocolServer

  from awslabs_core_mcp_server.model_context_protocol import InMemoryModelContextProtocolServer

Quickstart

This quickstart demonstrates how to instantiate and run an in-memory Model Context Protocol (MCP) server using `asyncio` and `websockets`. The server will listen for WebSocket connections and handle MCP requests. The `initial_data` argument is optional and can be used to pre-populate the server's context.

import asyncio
import websockets
from awslabs_core_mcp_server.model_context_protocol import InMemoryModelContextProtocolServer

async def run_server():
    # Example initial data (can be empty or loaded from a file)
    initial_data = {
        "context_id_1": {"model_id": "model_A", "context": {"key": "value"}}
    }
    
    # Initialize the in-memory MCP server with optional initial data
    server_instance = InMemoryModelContextProtocolServer(initial_data=initial_data)
    
    # Start the WebSocket server
    port = 8080
    host = "localhost"
    print(f"Starting MCP server on ws://{host}:{port}")
    async with websockets.serve(server_instance.handle_request, host, port):
        await asyncio.Future() # Run forever

if __name__ == "__main__":
    try:
        asyncio.run(run_server())
    except KeyboardInterrupt:
        print("\nServer stopped gracefully.")