Skip to main content

​
Overview

The MCP server has two transport modes. The transport determines how MCP messages are sent and received.

​
Stdio Transport

Default transport. The server reads MCP messages from stdin and writes responses to stdout. 
import { serve } from '@gizatech/mcp-server';

await serve(); // stdio by default
Or explicitly: 
await serve({ transport: 'stdio' });

​
When to Use Stdio

  • Claude Desktop, Cursor, Claude Code — these clients spawn the server as a child process and communicate over stdin/stdout
  • Local development — simple to run and debug
  • Any MCP client that manages the server process directly

​
How It Works

The client starts the server process and communicates via standard I/O pipes. The server runs as long as the client keeps the process alive.

​
HTTP Transport

The server starts an HTTP endpoint that accepts MCP messages via POST /mcp. 
import { serve } from '@gizatech/mcp-server';

await serve({ transport: 'http', port: 3000 });
Or via environment variables: 
export TRANSPORT=http
export PORT=3000
npx @gizatech/mcp-server

​
Endpoints

MethodPathDescription
POST/mcpMCP message endpoint (StreamableHTTP)
GET/healthHealth check (returns {"status": "ok"})

​
When to Use HTTP

  • Backend services that connect to the MCP server over the network
  • Multiple clients connecting to a single server instance
  • Containerized deployments (Docker, Kubernetes)
  • Custom integrations where stdio isn’t practical

​
Session Management

HTTP transport assigns each connection a unique session ID via crypto.randomUUID(). This enables multiple clients to connect to the same server instance without interfering with each other.

​
Health Check

Use the /health endpoint for load balancer or container orchestration health probes: 
curl http://localhost:3000/health
# {"status":"ok"}

​
Comparison

FeatureStdioHTTP
SetupZero configRequires port
ClientsDesktop apps (Claude, Cursor)Backend services, web apps
ConcurrencySingle clientMultiple clients
DeploymentLocal processContainerizable
NetworkNo network requiredRequires network access
Session isolationSingle sessionUUID per connection

​
Using Transport with the Server Class

When using GizaServer directly, call the transport method explicitly: 
import { GizaServer, resolveConfig } from '@gizatech/mcp-server';

const server = new GizaServer(resolveConfig());

// Stdio
await server.stdio();

// HTTP
await server.http({ port: 3000 });
The serve() function handles this automatically based on the transport config value.