forgejo-mcp/demos/streamable-http-transport.md

Demo: Streamable HTTP Transport

2026-03-28T00:00:00Z by Showboat 0.6.1

What this feature does

Adds --transport http to start the MCP server using the streamable HTTP transport from MCP spec 2025-03-26. This is the recommended transport for remote MCP servers and is required for compatibility with Claude.ai's custom MCP connector.

The three available transports are now:

Transport	Flag	Use case
stdio	--transport stdio (default)	Local CLI integration (Claude Code, etc.)
sse	--transport sse	Legacy remote server
http	--transport http	Recommended remote server (Claude.ai connectors, etc.)

Setup

Set FORGEJO_URL and FORGEJO_ACCESS_TOKEN environment variables (or use direnv), then build:

make build

Starting the server with streamable HTTP

Default port (8080)

./forgejo-mcp --transport http --url $FORGEJO_URL --token $FORGEJO_ACCESS_TOKEN

Starting Forgejo MCP Server ...
Starting MCP streamable HTTP server  {"port": 8080}
MCP streamable HTTP server ready for connections  {"port": 8080, "endpoint": "http://localhost:8080"}

Custom port

./forgejo-mcp --transport http --http-port 9090 --url $FORGEJO_URL --token $FORGEJO_ACCESS_TOKEN

Starting Forgejo MCP Server ...
Starting MCP streamable HTTP server  {"port": 9090}
MCP streamable HTTP server ready for connections  {"port": 9090, "endpoint": "http://localhost:9090"}

Connecting with an MCP client

Initialize session

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "demo-client", "version": "1.0" }
    }
  }'

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-03-26","capabilities":{"tools":{"listChanged":true},"logging":{}},"serverInfo":{"name":"Forgejo MCP Server","version":"..."}}}

List available tools

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <session-id-from-init>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"get_my_user_info","description":"Get current user info"}, ...]}}

Call a tool

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <session-id-from-init>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search_repos",
      "arguments": { "keyword": "forgejo-mcp" }
    }
  }'

{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"goern/forgejo-mcp ..."}]}}

Claude.ai custom connector

With the streamable HTTP transport, you can register forgejo-mcp as a custom MCP connector in Claude.ai:

1. Deploy forgejo-mcp with --transport http behind a public HTTPS endpoint
2. In Claude.ai settings, add a custom MCP connector pointing to your endpoint
3. Claude.ai will discover all Forgejo tools automatically

See Claude.ai MCP connector docs for setup details.

Transport comparison

Feature	stdio	SSE	Streamable HTTP
Local use	Yes	No	No
Remote use	No	Yes	Yes
Claude Code	Yes	Deprecated	Yes
Claude.ai connector	No	No	Yes
MCP spec status	Stable	Deprecated	Recommended
Stateful sessions	N/A	Yes	Yes