@cellium/mcp-client

A Model Context Protocol (MCP) server that provides both HTTP streaming and stdio transports to connect remote Cellium processor servers with MCP clients like Codex.

Features

• Dual Transport Support: Both HTTP streaming and stdio transport for maximum compatibility
• Auto-Detection: Automatically chooses appropriate transport based on execution context
• Authentication: Token-based authentication with format user:username:hash
• Robust Connection Management: Automatic reconnection with configurable retry logic
• MCP Protocol Compliance: Uses official @modelcontextprotocol/sdk
• CLI Interface: Ready-to-use command-line interface
• TypeScript Support: Full TypeScript types and definitions

Installation

npm install -g @cellium/mcp-client

Or use directly with npx:

npx @cellium/mcp-client

Usage

Command Line Interface

HTTP Streaming Mode (Default)

Perfect for direct connections to the MCP server:

# Using environment variable for token
export CELLIUM_MCP_TOKEN="user:your-username:your-hash"
cellium-mcp-client

# Using command line option
cellium-mcp-client --token "user:your-username:your-hash"

# With custom endpoint, port, and verbose logging
cellium-mcp-client \
  --token "user:your-username:your-hash" \
  --endpoint "https://mcp.cellium.dev/http-stream" \
  --port 3001 \
  --verbose \
  --retry-attempts 5 \
  --retry-delay 2000

Stdio Mode (Command-Based MCP Clients)

Perfect for command-based MCP clients like Codex:

# Explicit stdio mode
cellium-mcp-client --stdio --token "user:your-username:your-hash"

# Auto-detection when run by MCP clients (stdin is piped)
# This happens automatically when launched via MCP client configuration

Configuration with Codex/Other MCP Clients

Option 1: Direct HTTP Connection (Recommended for modern clients)

[mcp_servers.cellium]
url = "http://localhost:3001"
enabled = true

Option 2: Command-Based with Stdio Transport (Universal compatibility)

[mcp_servers.cellium]
command = "npx"
args = ["-y", "@cellium/mcp-client", "--stdio"]
env = { CELLIUM_MCP_TOKEN = "user:your-username:your-hash" }
enabled = true

Option 3: Command-Based with HTTP Auto-Start

[mcp_servers.cellium]
command = "npx"
args = ["-y", "@cellium/mcp-client"]
env = { CELLIUM_MCP_TOKEN = "user:your-username:your-hash" }
enabled = true

Programmatic Usage

import { CelliumMCPClient } from '@cellium/mcp-client';
import pino from 'pino';

const logger = pino();

// HTTP Streaming Mode
const httpClient = new CelliumMCPClient({
  token: 'user:your-username:your-hash',
  endpoint: 'https://mcp.cellium.dev/http-stream',
  httpPort: 3001,
  logger,
  retryAttempts: 3,
  retryDelay: 1000,
  useStdio: false
});

// Stdio Mode
const stdioClient = new CelliumMCPClient({
  token: 'user:your-username:your-hash',
  endpoint: 'https://mcp.cellium.dev/http-stream',
  logger,
  retryAttempts: 3,
  retryDelay: 1000,
  useStdio: true
});

await client.connect();
await client.serve();

// Handle shutdown gracefully
process.on('SIGINT', async () => {
  await client.disconnect();
  process.exit(0);
});

Configuration Options

| Option | Environment Variable | Description | Default | |--------|---------------------|-------------|---------| | --token | CELLIUM_MCP_TOKEN | Authentication token (required) | - | | --endpoint | - | Server endpoint URL | http://localhost:3000/http-stream | | --port | - | HTTP streaming port | 3001 | | --stdio | - | Force stdio transport | Auto-detected | | --verbose | - | Enable verbose logging | false | | --debug | - | Enable debug mode with extensive logging | false | | --retry-attempts | - | Number of retry attempts | 3 | | --retry-delay | - | Delay between retries (ms) | 1000 |

Transport Modes

HTTP Streaming Transport

• Use case: Direct connections from modern MCP clients
• Benefits: Persistent connections, multiple concurrent sessions, better scalability
• Connection: Client connects directly to http://localhost:3001 (or configured port)
• Communication: Server-Sent Events (SSE) for real-time streaming

Stdio Transport

• Use case: Command-based MCP clients (like traditional Codex configurations)
• Benefits: Universal compatibility, no port conflicts, standard MCP pattern
• Connection: MCP client launches process and communicates via stdin/stdout
• Communication: Standard input/output pipes

Auto-Detection Logic

The client automatically chooses the appropriate transport:

1. Explicit stdio: --stdio flag forces stdio transport
2. Auto-detected stdio: When stdin is piped (command-based execution)
3. Default HTTP: All other cases use HTTP streaming transport

Authentication Token Format

The authentication token must follow the format: user:username:hash

Where:

• user: Literal string "user"
• username: Your Cellium username
• hash: Authentication hash provided by Cellium

Example: user:john-doe:a1b2c3d4e5f6...

Architecture

┌─────────────────┐   HTTP/Stdio   ┌─────────────────┐   HTTPS    ┌─────────────────┐
│                 │◄──────────────►│                 │◄──────────►│                 │
│     Codex /     │   Streaming    │ cellium-mcp-    │    HTTP    │ Cellium Server  │
│  AI Assistant   │   or Pipes     │ client (Proxy)  │   Requests │   (Remote)      │
│   (Cody, etc.)  │   MCP Protocol │                 │            │                 │
└─────────────────┘                └─────────────────┘            └─────────────────┘

The client acts as a dual-transport MCP server that proxies requests between MCP clients and the remote Cellium processor server, handling:

• HTTP Streaming Transport: Provides streamable HTTP interface for direct client connection
• Stdio Transport: Traditional stdin/stdout communication for command-based clients
• Authentication: Token-based authentication with remote server
• Request Proxying: Converts MCP requests to HTTP requests to remote server
• Error Handling: Graceful handling of connection failures
• Connection Management: Automatic retry and reconnection logic

Development

# Clone and install dependencies
git clone <repo-url>
cd cellium-mcp-client
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Test locally
./dist/cli.js --help

Troubleshooting

Connection Issues

1. Invalid token format: Ensure your token follows the user:username:hash format
2. Network connectivity: Check if https://mcp.cellium.dev/http-stream is accessible
3. Authentication failed: Verify your token is valid and not expired
4. Port already in use: Change the --port option if port 3001 is already in use

Verbose Logging

Use --verbose flag to enable detailed logging for debugging:

cellium-mcp-client --verbose --token "your-token"

Common Error Messages

• Authentication token required: Set CELLIUM_MCP_TOKEN or use --token
• Invalid token format: Check token follows user:username:hash pattern
• Not connected to remote server: Connection to HTTP streaming endpoint failed
• Request timeout: Remote server didn't respond within 30 seconds
• EADDRINUSE: Port is already in use, try a different --port

Connecting with Codex

Make sure to connect your MCP client to the HTTP streaming server at:

http://localhost:3001

The server provides Server-Sent Events (SSE) streaming for real-time communication.

License

MIT

Support

For issues and questions, please open an issue on the GitHub repository.