From 608dccc9a7cf81e2d22c196f15c6533c772bac9c Mon Sep 17 00:00:00 2001 From: Molecule AI App-FE Date: Thu, 14 May 2026 16:50:25 +0000 Subject: [PATCH 1/2] fix(docs): combine MCP HTTP/SSE transport + env vars (closes PR #42, #43) --- content/docs/mcp-server.mdx | 37 ++++++++++++++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/content/docs/mcp-server.mdx b/content/docs/mcp-server.mdx index 208beca..d1d0e68 100644 --- a/content/docs/mcp-server.mdx +++ b/content/docs/mcp-server.mdx @@ -25,7 +25,8 @@ npx @molecule-ai/mcp-server@1.0.0 "command": "npx", "args": ["@molecule-ai/mcp-server@1.0.0"], "env": { - "MOLECULE_URL": "http://localhost:8080" + "MOLECULE_URL": "http://localhost:8080", + "MOLECULE_API_KEY": "your-bearer-token" } } } @@ -36,10 +37,11 @@ npx @molecule-ai/mcp-server@1.0.0 **Pin the package version.** The examples above use `@1.0.0` — always specify an exact version and omit the `-y` flag. An unpinned `npx -y @molecule-ai/mcp-server` (no version) silently installs whatever npm serves on the next restart; if the package is ever compromised, it runs with your full MCP client permissions. Check [npm](https://www.npmjs.com/package/@molecule-ai/mcp-server) for the latest stable release before upgrading. -For SaaS deployments, set `MOLECULE_URL` to your tenant URL: +For SaaS deployments, set `MOLECULE_URL` to your tenant URL and add your API key: ```json -"MOLECULE_URL": "https://your-org.moleculesai.app" +"MOLECULE_URL": "https://your-org.moleculesai.app", +"MOLECULE_API_KEY": "your-bearer-token" ``` ### Verify @@ -152,6 +154,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 +189,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 | -- 2.45.2 From b4488b224f41983ccc1b5fd32ca8ab7f6136200b Mon Sep 17 00:00:00 2001 From: Molecule AI App-FE Date: Thu, 14 May 2026 18:49:20 +0000 Subject: [PATCH 2/2] fix(docs): remove non-existent HTTP/SSE transport and MCP_SERVER_PORT MCP server source confirms: - Only StdioServerTransport exists (no HTTP/SSE server) - No MCP_SERVER_PORT env var - apiCall() sends no Authorization header Removed the entire "Transport modes" section (non-existent HTTP/SSE endpoint), MCP_SERVER_PORT row from env table and troubleshooting, and MOLECULE_API_KEY from config examples (auth is planned, not wired yet). Replaced with accurate "Transport" section documenting stdio-only mode. Co-Authored-By: Claude Opus 4.7 --- content/docs/mcp-server.mdx | 40 ++++++++----------------------------- 1 file changed, 8 insertions(+), 32 deletions(-) diff --git a/content/docs/mcp-server.mdx b/content/docs/mcp-server.mdx index d1d0e68..3e28e23 100644 --- a/content/docs/mcp-server.mdx +++ b/content/docs/mcp-server.mdx @@ -25,8 +25,7 @@ npx @molecule-ai/mcp-server@1.0.0 "command": "npx", "args": ["@molecule-ai/mcp-server@1.0.0"], "env": { - "MOLECULE_URL": "http://localhost:8080", - "MOLECULE_API_KEY": "your-bearer-token" + "MOLECULE_URL": "http://localhost:8080" } } } @@ -37,13 +36,14 @@ npx @molecule-ai/mcp-server@1.0.0 **Pin the package version.** The examples above use `@1.0.0` — always specify an exact version and omit the `-y` flag. An unpinned `npx -y @molecule-ai/mcp-server` (no version) silently installs whatever npm serves on the next restart; if the package is ever compromised, it runs with your full MCP client permissions. Check [npm](https://www.npmjs.com/package/@molecule-ai/mcp-server) for the latest stable release before upgrading. -For SaaS deployments, set `MOLECULE_URL` to your tenant URL and add your API key: +For SaaS deployments, set `MOLECULE_URL` to your tenant URL: ```json -"MOLECULE_URL": "https://your-org.moleculesai.app", -"MOLECULE_API_KEY": "your-bearer-token" +"MOLECULE_URL": "https://your-org.moleculesai.app" ``` +Auth via `MOLECULE_API_KEY` is planned for a future release. + ### Verify Once configured, your MCP client should show 87 Molecule AI tools. Test with: @@ -154,34 +154,11 @@ 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 | +| `MOLECULE_API_KEY` | — | Bearer token for platform authentication (planned) | -## Transport modes +## Transport -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. +The MCP server uses **stdio transport** — the client (Claude Code, Cursor, etc.) spawns the 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. ## Troubleshooting @@ -189,5 +166,4 @@ Configure your MCP client to connect over HTTP. The server emits `data: null` he |---|---| | 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 | -- 2.45.2