MCP Streamable HTTP Server Example
This directory contains an example implementation of a Model Context Protocol (MCP) server using the @modelcontextprotocol/sdk.
It utilizes the StreamableHTTPServerTransport to handle MCP communication over HTTP, supporting bidirectional communication including server-sent events (SSE) for notifications.
It also includes the simpleStreamableHttpClient.ts to start a client and interact with the server
Features
- Implements the Model Context Protocol (MCP).
- Uses
StreamableHTTPServerTransportfor HTTP-based communication. - Manages client sessions using the
mcp-session-idheader. - Handles client requests (POST), server notifications (GET via SSE), and session termination (DELETE).
- Includes a basic example tool (
echo). - Built with TypeScript and hono server.
Prerequisites
- Node.js (version recommended by the project, e.g., >= 18)
- npm or yarn
Installation
- Navigate to the
docebo-mcp-serverdirectory:cd docebo-mcp-server - Install dependencies:
npm install
Building
To compile the TypeScript code to JavaScript:
npm run build
This will output the compiled files to a build directory.
By default, the server listens on port 3000 and exposes the MCP endpoint at /mcp.
API Endpoint
- URL:
/mcp - Methods:
POST: Used by clients to send requests (including the initialinitializerequest).GET: Used by clients to establish an SSE connection for receiving server-to-client notifications.DELETE: Used by clients to terminate the current MCP session.
Session Management
The server manages client sessions using the mcp-session-id HTTP header.
- When a client sends an
initializerequest without a session ID, the server creates a new session and a new transport, returning thesessionIdin the response. - Subsequent requests (POST, GET, DELETE) from the client must include the assigned
mcp-session-idheader for the server to route the request to the correct transport instance. - The
DELETE /mcprequest terminates the session associated with the providedmcp-session-id.
Tools
Tools can be added in the tools directory
Run the Server
npm run dev:hono
Running the Client
Use the MCP inspector
npx @modelcontextprotocol/inspector
or you can use a CLI
npm run start:simpleClient
You can use the commands shown in this client to interact with the server, like
list-tools
Claude Desktop as of this writing doesn't support HttpStreamable protocol. Add the server configuration to your Claude Desktop config file (usually located at ~/Library/Application Support/Claude/claude_desktop_config.json in macOS) and restart Claude Desktop:
{
"mcpServers": {
"docebo": {
"command": "npx",
"args": ["mcp-remote", "http://127.0.0.1:3000/mcp"],
"env": {
"BEARER_TOKEN_BEARERAUTH": "<your_token>"
}
}
}
}
Remote MCP Server are still being developed/enhanced by different MCP Hosts like Claude Desktop.
MCP servers can be deployed in 2 different ways:
- Local MCP Server with Remote API
graph LR
subgraph "Your Computer"
C1[MCP Host w/ Client]
S1[MCP Server]
end
subgraph "Remote Servers"
API1[Remote API]
end
C1 <--> S1
S1 <--> API1
style C1 fill:#2e7d32,color:#ffffff
style S1 fill:#f57c00,color:#ffffff
style API1 fill:#c2185b,color:#ffffff
- Local Host/Client connecting to Remote MCP Server
graph LR
subgraph "Your Computer "
C2[MCP Host w/ Client]
end
subgraph "Remote Server"
S2[MCP Server]
API2[Remote API]
end
C2 <-.-> S2
S2 <--> API2
style C2 fill:#2e7d32,color:#ffffff
style S2 fill:#f57c00,color:#ffffff
style API2 fill:#c2185b,color:#ffffff
There are 2 forms of authorization:
- MCP protocol provides authorization capabilities at the transport level, enabling MCP clients to make requests to restricted MCP servers on behalf of resource owners. This is what the new Authorization proposal addresses.
- The MCP Server needs to know how to authenticate with the remote APIs as well.
This application needs a bearer token that is then passed from the MCP Client to the MCP Server and the MCP Server uses this to call the remote APIs. This system is not ideal if the MCP Server have to deal with more than one remote API system.