Segment MCP Server

A Model Context Protocol (MCP) server for Segment's Profile API and AI Copilot tracking capabilities. This package provides both a ready-to-use CLI tool and a modular library for building custom MCP servers.

Features

• 🔌 Multiple Transport Support: Stdio for local development, HTTP for remote deployment
• 📊 Segment Profile API: Access user profiles, traits, and events
• 🤖 AI Tracking: Built-in tools for tracking AI conversations and interactions
• 🔧 Modular Architecture: Use as a library or CLI tool
• 🛡️ Type Safe: Full TypeScript support
• 🌐 Multi-Session HTTP: Support for multiple concurrent MCP sessions over HTTP

Installation

npm install segment-mcp-server

Quick Start

As a CLI Tool

# Set your environment variables
export SEGMENT_PROFILE_API_TOKEN="your_token"
export SEGMENT_TRACKING_WRITE_KEY="your_write_key"
export SEGMENT_WORKSPACE_ID="your_workspace_id"
export SEGMENT_SPACE_ID="your_space_id"

# Run with stdio transport (default)
segment-mcp-server

# Run with HTTP transport
export MCP_TRANSPORT=http
export HTTP_PORT=3000
segment-mcp-server

As a Library

import {
  SegmentMcp,
  createStdioTransport,
  createHttpTransport,
  loadConfig,
} from "segment-mcp-server";

// Create the server
const config = loadConfig();
const server = new SegmentMcp({ config });

// Option 1: Stdio transport
const stdioTransport = createStdioTransport();
await server.start(stdioTransport);

// Option 2: HTTP transport
const httpTransport = createHttpTransport();
await server.start(httpTransport);

Modular Architecture

The package is designed with separation of concerns:

// Core server (no transport dependencies)
import { SegmentMcp } from "segment-mcp-server/server";

// Transport utilities
import {
  createStdioTransport,
  createHttpTransport,
} from "segment-mcp-server/transports";

// Configuration utilities
import { loadConfig, validateConfig } from "segment-mcp-server/config";

Transport Options

Stdio Transport

Perfect for local development and CLI usage:

import {
  SegmentMcp,
  createStdioTransport,
  loadConfig,
} from "segment-mcp-server";

const config = loadConfig();
const server = new SegmentMcp({ config });
const transport = createStdioTransport();

await server.start(transport);
console.log("Server running with stdio transport");

HTTP Transport (Single Session)

For simple HTTP deployments:

import {
  SegmentMcp,
  createHttpTransport,
  loadConfig,
} from "segment-mcp-server";

const config = loadConfig();
const server = new SegmentMcp({ config });

const transport = createHttpTransport({
  enableJsonResponse: true,
});

await server.start(transport);
console.log("Server running with HTTP transport");

HTTP Server (Multi-Session)

For production deployments supporting multiple concurrent sessions:

import {
  SegmentMcp,
  createHttpTransportManager,
  loadConfig,
} from "segment-mcp-server";

const config = loadConfig();
config.httpPort = 3000;
config.httpHost = "0.0.0.0";

const server = new SegmentMcp({ config });
const httpManager = createHttpTransportManager(server.getServer(), config);

await httpManager.start();
console.log(`Multi-session HTTP server running on port ${config.httpPort}`);

// Graceful shutdown
process.on("SIGINT", async () => {
  await httpManager.stop();
  process.exit(0);
});

Available Tools

Profile Tools

• get_profile_traits: Retrieve user profile traits
• get_profile_events: Get user events and interactions
• get_profile_past_chat: Access past conversation history

Tracking Tools

• track_ai_conversation: Track AI conversation events
• track_ai_query: Track individual AI queries
• track_ai_feedback: Track user feedback on AI responses
• track_custom_event: Track custom events
• identify_user: Identify and update user profiles

Configuration

Environment Variables

# Required
SEGMENT_PROFILE_API_TOKEN=your_profile_api_token
SEGMENT_TRACKING_WRITE_KEY=your_tracking_write_key
SEGMENT_WORKSPACE_ID=your_workspace_id
SEGMENT_SPACE_ID=your_space_id

# Optional
SEGMENT_PROFILE_API_BASE_URL=https://profiles.segment.com
SEGMENT_TRACKING_API_BASE_URL=https://api.segment.io/v1
LOG_LEVEL=info
API_RATE_LIMIT_PER_MINUTE=60

# Transport configuration
MCP_TRANSPORT=stdio  # or "http"
HTTP_PORT=3000
HTTP_HOST=0.0.0.0

Programmatic Configuration

import { SegmentMcp, SegmentConfig } from "segment-mcp-server";

const config: SegmentConfig = {
  profileApiToken:
    "vGzKEqx0hpXIA7z0JwRp_0Fw0BeUrL-wdLPxwrCeV8smuKnHnlDgbjo_nRwsZMnsWofjVkdwQiHDCqpI3XI0aWYgE8Bjeq-oZpO8UDHvVYRteMcfzPykgZnaI5_24xOFXHK8Fp9hrIhTpYYerQV_ZZbLmqyoB5eueHvGq5W_BMCzc-fFDwVqq2ByjhY5f_xo-kJ_LqhhThxrtFO1DWIFEX-zyq5VbLyzGCBnKu7jfxf1L82ZQV5mRN00ICpp-W99VQ==",
  trackingWriteKey: "rLNeLldLBz1tJ9jOjTGeU8hEQywSaFhS",
  workspaceId: "9rPVQSx1K1",
  spaceId: "spa_1bnL856M3JaIoKvx7fQQu0uCvqu",
  profileApiBaseUrl: "https://profiles.segment.com",
  trackingApiBaseUrl: "https://api.segment.io/v1",
  logLevel: "info",
  rateLimit: 60,
  transport: "http",
  httpPort: 3000,
  httpHost: "0.0.0.0",
};

const server = new SegmentMcp({
  config,
  name: "my-segment-server",
  version: "1.0.0",
});


## Examples

Run the included examples:

```bash
# Basic usage examples
npm run example:basic stdio
npm run example:basic http

# HTTP server management examples
npm run example:http manager
npm run example:http utility

HTTP API Endpoints

When running in HTTP mode, the following endpoints are available:

• POST /mcp - Main MCP protocol endpoint
• GET /mcp - Server-sent events for notifications (optional)
• DELETE /mcp - Session termination
• GET /health - Health check endpoint

Session Management

HTTP transport supports multiple concurrent sessions. Each session is identified by the Mcp-Session-Id header:

# Initialize a new session
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"test-client","version":"1.0.0"}}}'

# Use the returned session ID for subsequent requests
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: your-session-id" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Clean build artifacts
npm run clean

TypeScript Support

Full TypeScript definitions are included:

import {
  SegmentMcp,
  SegmentMcpOptions,
  SegmentConfig,
  HttpTransportOptions,
  HttpTransportManager,
} from "segment-mcp-server";

License

ISC

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request