Remote Deployment (Ops)

The HTTP transport enables remote access to Workflow MCP with optional OAuth authentication.

Hosted Service

Users should connect to:

https://api.workflow-mcp.blackmesa.live/mcp

Running Your Own (Internal)

# Install
npm install @blackmesa/workflow-mcp-http

# Run
MCP_PORT=3000 npx @blackmesa/workflow-mcp-http

Environment Variables

Variable	Default	Description
`PORT`	`3000`	Server port (Render/Heroku standard)
`MCP_PORT`	`3000`	Server port (fallback)
`MCP_HOST`	`0.0.0.0`	Bind address
`MCP_BASE_PATH`	`/mcp`	MCP endpoint path
`MCP_WORKSPACE_DIR`	`cwd`	Session file directory
`CORS_ORIGINS`	`*`	Allowed origins
`MCP_OAUTH_ENABLED`	`false`	Enable GitHub OAuth
`GITHUB_CLIENT_ID`	-	OAuth client ID
`GITHUB_CLIENT_SECRET`	-	OAuth secret

Endpoints

Method	Path	Description
`POST`	`/mcp`	Main request handler
`GET`	`/mcp`	SSE stream for notifications
`DELETE`	`/mcp`	Session termination
`GET`	`/health`	Health check

Connecting from a Client

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(
  new URL('https://your-server.com/mcp')
);

const client = new Client({ name: 'my-client', version: '1.0.0' });
await client.connect(transport);

OAuth Authentication

When MCP_OAUTH_ENABLED=true, the server requires a valid GitHub access token:

const transport = new StreamableHTTPClientTransport(
  new URL('https://your-server.com/mcp'),
  {
    requestInit: {
      headers: {
        'Authorization': `Bearer ${githubAccessToken}`
      }
    }
  }
);

Setting Up GitHub OAuth

Create a GitHub OAuth App at https://github.com/settings/developers
Set callback URL to your server
Copy Client ID and Secret

Set environment variables:

MCP_OAUTH_ENABLED=true
GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret

Session Management

Sessions are stored in memory with automatic cleanup:

Sessions expire after 1 hour of inactivity
Cleanup runs every minute
Session count available via /health endpoint

Production Considerations

Scaling

The HTTP server is stateful (sessions in memory). For horizontal scaling:

Use sticky sessions/session affinity
Or implement a shared session store (Redis)

Workspace Directory

Set MCP_WORKSPACE_DIR to a persistent volume:

MCP_WORKSPACE_DIR=/data/workflow

CORS

For browser-based clients, configure allowed origins:

CORS_ORIGINS=https://app.example.com,https://admin.example.com