molecule-ai/docs
38
0
Fork 0
Code Issues Pull Requests 16 Actions Packages Projects Releases Wiki Activity

docs(mcp): document HTTP/SSE transport mode + add missing env vars
All checks were successful
Secret scan / secret-scan (pull_request) Successful in 29s
Details
CI / build (pull_request) Successful in 2m18s
Details

Browse Source 
Gap-fill: the MCP server supports HTTP/SSE transport (controlled by
MCP_SERVER_PORT) but this was only mentioned in the server's internal
README, not in the public docs. This adds a "Transport modes" section
explaining stdio (default, for Claude Code/Cursor) and HTTP/SSE (for
remote agents and headless clients), including the SSE heartbeat
behaviour.

Also adds MOLECULE_API_KEY and MCP_SERVER_PORT to the env vars table
(gap identified in PR #42), and a troubleshooting entry for port-in-use.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Molecule AI · technical-writer 2026-05-14 09:56:05 +00:00
parent 3b381a49da
commit a303a3ecf1
1 changed files with 29 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
content/docs/mcp-server.mdx
View File

@ -152,6 +152,34 @@ The MCP server exposes tools across these categories:
| Variable | Default | Description |
|---|---|---|
| `MOLECULE_URL` | `http://localhost:8080` | Platform API URL |
| `MOLECULE_API_KEY` | — | Bearer token for platform authentication |
| `MCP_SERVER_PORT` | `3000` | TCP port for HTTP/SSE transport |
## Transport modes
The MCP server supports two transport modes:
### stdio (default, for local AI clients)
Claude Code, Cursor, and similar local AI clients use stdio transport. The client spawns the MCP server as a child process and communicates via JSON-RPC over stdin/stdout. Configure in your AI client's `mcp.json` as shown in Quick start above.
### HTTP/SSE (for remote agents and headless clients)
For agents running on remote servers or in environments where stdio is not available, the MCP server exposes an HTTP endpoint with Server-Sent Events (SSE) for streaming responses. The agent card and tool responses are available at:
```
http://localhost:3000/agent/card # MCP server info + tool manifest
http://localhost:3000/ # SSE stream for responses
```
Start the server in HTTP/SSE mode:
```bash
MCP_SERVER_PORT=3000 npm start
# Server starts on http://localhost:3000
```
Configure your MCP client to connect over HTTP. The server emits `data: null` heartbeats every 30 seconds on idle connections to keep proxies and load balancers from closing the SSE stream.
## Troubleshooting
@ -159,4 +187,5 @@ The MCP server exposes tools across these categories:
|---|---|
| Connection refused | Check `MOLECULE_URL` points to running platform |
| 401 Unauthorized | Token expired or revoked — create a new one |
| Port already in use | Set `MCP_SERVER_PORT` to an available port if 3000 is taken |
| Tools not showing | Run `npx @molecule-ai/mcp-server@1.0.0` standalone to check errors |