Skip to main content

​
Overview

xmcp supports two transport protocols for MCP communication:
  • HTTP Transport - RESTful API over HTTP/HTTPS, ideal for web clients and remote connections
  • STDIO Transport - Standard input/output communication, perfect for local CLI tools and desktop applications
Configure your transport in xmcp.config.ts based on your deployment needs.

​
HTTP Transport

HTTP transport exposes your MCP server as a RESTful API over HTTP/HTTPS.

​
Basic Configuration

examples/http-transport/xmcp.config.ts
import { XmcpConfig } from "xmcp";

const config: XmcpConfig = {
  http: {
    port: 3002,
  },
};

export default config;

​
Enabling HTTP Transport

Use the http key in your config: 
import { XmcpConfig } from "xmcp";

const config: XmcpConfig = {
  // Simple boolean to use defaults
  http: true,
  
  // Or configure specific options
  http: {
    port: 3000,
  },
};

export default config;

​
HTTP Configuration Options

​
http
boolean | object
Enable HTTP transport. Use true for defaults or an object for custom configuration
​
http.port
number
default:"3000"
Port number for the HTTP server

​
Starting the HTTP Server

npx xmcp dev
Your server will be available at http://localhost:3002/mcp (or your configured port).

​
HTTP Endpoints

The HTTP transport automatically creates MCP-compliant endpoints:
  • POST /mcp - Main MCP protocol endpoint
  • GET /health - Health check endpoint
  • GET /.well-known/oauth-protected-resource - OAuth discovery (if auth configured)

​
Example Tool with HTTP

examples/http-transport/src/tools/greet.ts
import { z } from "zod";
import { type InferSchema, type ToolMetadata } from "xmcp";

export const schema = {
  name: z.string().describe("The name of the user to greet"),
};

export const metadata: ToolMetadata = {
  name: "greet",
  description: "Greet the user",
  annotations: {
    title: "Greet the user",
    readOnlyHint: true,
    destructiveHint: false,
    idempotentHint: true,
  },
};

export default function greet({ name }: InferSchema<typeof schema>) {
  return `Hello, ${name}!!`;
}

​
When to Use HTTP

Web Applications

Connect from web browsers, React apps, or any HTTP client

Remote Access

Access your MCP server from different machines or networks

Cloud Deployment

Deploy to serverless platforms, containers, or cloud providers

Authentication

Use middleware for API keys, JWT, OAuth, or custom auth

​
STDIO Transport

STDIO transport uses standard input/output for process-to-process communication.

​
Basic Configuration

examples/stdio-transport/xmcp.config.ts
import { XmcpConfig } from "xmcp";

const config: XmcpConfig = {
  stdio: true,
};

export default config;

​
Starting with STDIO

npx xmcp dev
The server communicates via stdin/stdout. Client applications spawn this process and communicate through pipes.

​
STDIO Communication Flow

  1. Client spawns your MCP server as a subprocess
  2. Client sends JSON-RPC messages to stdin
  3. Server processes requests and responds via stdout
  4. Server logs and errors go to stderr

​
Example Tool with STDIO

examples/stdio-transport/src/tools/greet.ts
import { z } from "zod";
import { type InferSchema, type ToolMetadata } from "xmcp";

export const schema = {
  name: z.string().describe("The name of the user to greet"),
};

export const metadata: ToolMetadata = {
  name: "greet",
  description: "Greet the user",
  annotations: {
    title: "Greet the user",
    readOnlyHint: true,
    destructiveHint: false,
    idempotentHint: true,
  },
};

export default async function greet({ name }: InferSchema<typeof schema>) {
  const result = `Hello, ${name}!`;

  return {
    content: [{ type: "text", text: result }],
  };
}

​
When to Use STDIO

Desktop Applications

Integrate with Electron apps, Claude Desktop, or native applications

CLI Tools

Build command-line tools that communicate via stdin/stdout

Local Development

Fast local testing without network overhead

Process Isolation

Each client gets its own isolated server process

​
Dual Transport Support

You can enable both transports simultaneously: 
import { XmcpConfig } from "xmcp";

const config: XmcpConfig = {
  http: {
    port: 3002,
  },
  stdio: true,
};

export default config;
This allows your server to be accessed both locally via STDIO and remotely via HTTP.

​
Transport Comparison

FeatureHTTPSTDIO
Remote Access✅ Yes❌ No (local only)
Authentication✅ Middleware support⚠️ Limited
Web Browsers✅ Yes❌ No
Desktop Apps⚠️ Via network✅ Native
Deployment✅ Cloud-ready⚠️ Local only
Performance⚠️ Network overhead✅ Fast IPC
Process ModelShared serverIsolated per client

​
Development Tips

Test Locally First

Use STDIO during development for faster iteration without network setup

Deploy with HTTP

Switch to HTTP for production deployments and cloud hosting

Enable Both

Support both transports for maximum flexibility

Use TypeScript

Enable skipTypeCheck: false in production for type safety

​
TypeScript Configuration

Both examples include TypeScript options:
examples/http-transport/xmcp.config.ts
import { XmcpConfig } from "xmcp";

const config: XmcpConfig = {
  http: {
    port: 3002,
  },
  typescript: {
    skipTypeCheck: true,
  },
};

export default config;
Set skipTypeCheck: false in production to catch type errors before deployment.

​
Next Steps

Client Connections

Connect to other MCP servers as a client

Authentication

Secure your HTTP transport with authentication

Middleware

Add custom middleware to HTTP transport

Deployment

Deploy your MCP server to production

Build docs developers (and LLMs) love

Get started for freeTalk to us