e7283d8d4e
Add --transport http using MCP spec 2025-03-26 streamable HTTP, the recommended transport for remote servers and Claude.ai connectors. Includes --http-port flag, showboat demo, and openspec plan.
133 lines
3.8 KiB
Markdown
133 lines
3.8 KiB
Markdown
# Demo: Streamable HTTP Transport
|
|
|
|
*2026-03-28T00:00:00Z by Showboat 0.6.1*
|
|
<!-- showboat-id: a3f8b21c-streamable-http-demo-2026 -->
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
make build
|
|
```
|
|
|
|
## Starting the server with streamable HTTP
|
|
|
|
### Default port (8080)
|
|
|
|
```bash
|
|
./forgejo-mcp --transport http --url $FORGEJO_URL --token $FORGEJO_ACCESS_TOKEN
|
|
```
|
|
|
|
```output
|
|
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
|
|
|
|
```bash
|
|
./forgejo-mcp --transport http --http-port 9090 --url $FORGEJO_URL --token $FORGEJO_ACCESS_TOKEN
|
|
```
|
|
|
|
```output
|
|
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
|
|
|
|
```bash
|
|
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" }
|
|
}
|
|
}'
|
|
```
|
|
|
|
```output
|
|
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-03-26","capabilities":{"tools":{"listChanged":true},"logging":{}},"serverInfo":{"name":"Forgejo MCP Server","version":"..."}}}
|
|
```
|
|
|
|
### List available tools
|
|
|
|
```bash
|
|
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": {}
|
|
}'
|
|
```
|
|
|
|
```output
|
|
{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"get_my_user_info","description":"Get current user info"}, ...]}}
|
|
```
|
|
|
|
### Call a tool
|
|
|
|
```bash
|
|
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" }
|
|
}
|
|
}'
|
|
```
|
|
|
|
```output
|
|
{"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](https://support.claude.com/en/articles/11503834-building-custom-connectors-via-remote-mcp-servers) 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 |
|