Add Streamable HTTP Support and Graceful Shutdown for Postgres MCP Server

[ahmedmustahid]

Summary

This PR implements streamable HTTP transport support and fixes graceful shutdown handling for the Postgres MCP server, addressing issues with signal handling in stdio transport environments.

Changes Made

Core Improvements

• Streamable HTTP Transport: Added support for HTTP-based communication alongside existing stdio transport
• Graceful Shutdown: Implemented proper signal handling that works reliably with both stdio and HTTP transports

Modified Files

• src/postgres_mcp/__init__.py: Simplified main entry point to properly delegate to server.main()
• src/postgres_mcp/server.py: Enhanced with streamable HTTP support and robust shutdown handling

Key Features

• Multi-transport Support: Server now supports all of stdio, sse and streamable HTTP
• Signal Handling: Proper SIGINT/SIGTERM handling that actually terminates the process
• Database Cleanup: Ensures database connections are properly closed during shutdown

Problem Solved

Previously,

• there was no streamable http support
• pressing Ctrl+C would trigger "asyncio.run() cannot be called from a running event loop" error

Solution

• Implemented threading-based signal handling that works with blocked event loops
• Added streamable HTTP transport as an alternative to stdio
• Simplified shutdown logic with proper resource cleanup
• Used appropriate exit mechanisms for different transport types

Testing

• ✅ Ctrl+C properly terminates the server
• ✅ Database connections are closed cleanly
• ✅ Works with both stdio and HTTP transports

Backward Compatibility

• All existing MCP client integrations continue to work unchanged
• Stdio transport remains the default for MCP usage
• HTTP transport is available as an optional feature

Usage Examples

Default MCP Usage (stdio)

uv run postgres-mcp  # Uses stdio transport as before

Streamable HTTP Usage

# uv run postgres-mcp --transport sse  #sse
uv run postgres-mcp --transport streamable_http # Enables HTTP transport

Notes

• Fixes the "asyncio.run() cannot be called from a running event loop" error
• Resolves process hanging issues during shutdown
• Maintains full compatibility with existing MCP client implementations
• Adds foundation for future web-based management interfaces

---

Type: Enhancement, Bug Fix
Breaking Changes: None
Requires Migration: No

---

Fixes #102

[ahmedmustahid]

@jssmith Hello, sorry for pinging you on this. Would you please review the PR and merge if the review is passed. Thank you.

[Saifullah3711]

When I run the MCP inspector, it shows this now with SSE
NOTE: The sse transport is deprecated and has been replaced by StreamableHttp
Thanks @ahmedmustahid for this support.
@jssmith can you please review the code and merge with main?

[mavogel]

@jssmith | @mdashti | @greglearns can we merge this PR? :)

We would like to migrate all the MCP servers we use to streamable http

[ivanbaldo]

This fixes #102

[mschmill]

Is this on the release schedule anywhere? Streamable HTTP seems like a pretty important use case.

[mavogel]

Unfortunately, there is no reponse for merging this change. I saw 2 options

1. I could get it work with Q developer cli 1.19.3 and the http protocol, as it can handle the sse as fallback

{
  "mcpServers": {
    "postgres": {
      "type": "http",
      "url": "https://postgres-url.com/sse"
    }
  }
}

2. I took the code from the PR, build the docker image and hosted it in a private registry. Not optimal, but works.

Or switch to another one: https://www.pulsemcp.com/servers/modelcontextprotocol-postgres

[mschmill]

Unfortunately, there is no reponse for merging this change.

Thanks for your reply. I saw that there were others who wanted this to move forward, I was hoping a little more interest might get a bump here but I'll take a look at alternatives.

[mavogel]

FYI I pinged @jssmith directly on LinkedIn and he said he'll take a look this week :) maybe he'd promote sb to be a maintainer

[adrian-chang-alcover]

Unfortunately, there is no reponse for merging this change. I saw 2 options

1. I could get it work with Q developer cli 1.19.3 and the http protocol, as it can handle the sse as fallback

{
  "mcpServers": {
    "postgres": {
      "type": "http",
      "url": "https://postgres-url.com/sse"
    }
  }
}

2. I took the code from the PR, build the docker image and hosted it in a private registry. Not optimal, but works.

Or switch to another one: https://www.pulsemcp.com/servers/modelcontextprotocol-postgres

Hi @mavogel
Could you share how you deployed it ? I am doing the same, build an image from the PR.
And then deploy it on ECS Fargate behind an ALB, but I am not able to connect Claude Web to it.
I am suspecting the ALB is breaking the Streamable HTTP.
Does it make sense ?

[jssmith]

Thanks for this contribution @ahmedmustahid!

We've created #134 which extracts just the streamable HTTP transport functionality from this PR, with tests added. It credits you as a co-author.

The signal handling improvements from this PR will be addressed in a separate follow-up PR to keep the changes focused and easier to review.

If #134 is merged, this PR can be closed (or updated to focus only on the signal handling portion if you'd like to continue with that).