Internal Data MCP Server

Internal Data MCP Server

A production-grade Model Context Protocol (MCP) server that exposes internal employee directory and project management systems to AI models.

Overview

This MCP server standardizes how AI assistants access your internal data. Instead of building custom integrations for each AI model, you define your data once, and any MCP-compatible client—Claude, ChatGPT, or your custom app—can use it without modification.

Key Capabilities

• Employee Directory Search – Find team members by name, email, role, or department
• Project Management – Query active, completed, and on-hold projects
• Team Composition – Identify who's working on what projects
• Organization Structure – Explore departments and team hierarchies
• Secure Access Control – Role-based data filtering per user
• Audit Logging – Complete audit trail of all data access
• Production Ready – Health checks, error handling, Docker-ready

Architecture

┌─────────────────┐
│   AI Models     │
│  (Claude, etc)  │
└────────┬────────┘
         │
    HTTP/stdio
         │
┌────────▼──────────────────────┐
│    MCP Server (Node.js)        │
│  - Tools (Data Operations)     │
│  - Resources (Context Data)    │
│  - Authentication/Audit        │
└────────┬──────────────────────┘
         │
    ┌────┴──────┬──────────┐
    │            │          │
┌───▼──┐    ┌────▼───┐  ┌──▼────┐
│ DB   │    │ APIs   │  │ Docs   │
└──────┘    └────────┘  └────────┘

Quick Start

Prerequisites

• Node.js 22+
• npm or yarn
• PostgreSQL (for production use; can be mocked in dev)

Installation

# Clone or download the repository
cd internal-data-mcp

# Install dependencies
npm install

# Build TypeScript
npm run build

Development

# Run the HTTP server (dev mode)
npm run dev

# Run with stdio transport (for Claude Desktop)
npm run stdio

# Type check
npm run type-check

The server will start on http://localhost:3100/mcp by default.

Production

# Build for production
npm run build

# Start the server
npm start

# Or use Docker
docker build -t internal-data-mcp .
docker run -p 3100:3100 -e INTERNAL_DB_URL="postgres://..." internal-data-mcp

Configuration

Environment Variables

# Database connection string
INTERNAL_DB_URL=postgres://user:password@localhost/internal_data

# Server port (default: 3100)
PORT=3100

# Node environment
NODE_ENV=production

Database Schema

The server expects the following PostgreSQL tables:

-- Employees table
CREATE TABLE employees (
  id UUID PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT UNIQUE NOT NULL,
  department TEXT NOT NULL,
  role TEXT NOT NULL,
  manager_id UUID,
  start_date DATE NOT NULL
);

-- Projects table
CREATE TABLE projects (
  id UUID PRIMARY KEY,
  name TEXT NOT NULL,
  status VARCHAR(20) NOT NULL CHECK (status IN ('active', 'completed', 'on_hold')),
  lead_id UUID NOT NULL REFERENCES employees(id),
  department TEXT NOT NULL,
  deadline DATE
);

-- Project members bridge table
CREATE TABLE project_members (
  project_id UUID NOT NULL REFERENCES projects(id),
  employee_id UUID NOT NULL REFERENCES employees(id),
  PRIMARY KEY (project_id, employee_id)
);

API Endpoints

Core MCP Endpoint

• POST/GET /mcp – Main MCP protocol endpoint (requires authentication)

Health Checks

• GET /health – Full health check with dependency status
• GET /health/live – Liveness probe
• GET /health/ready – Readiness probe

Information

• GET /info – Server capabilities and available tools

Tools

search_employees

Search the employee directory by name, email, or role.

Parameters:

• query (string, required) – Search term
• department (string, optional) – Filter by department

Example:

{
  "name": "search_employees",
  "arguments": {
    "query": "engineer",
    "department": "Engineering"
  }
}

list_projects

List projects filtered by status.

Parameters:

• status (enum["active", "completed", "on_hold"], required) – Project status

Example:

{
  "name": "list_projects",
  "arguments": {
    "status": "active"
  }
}

get_project_team

Get all team members for a specific project.

Parameters:

• project_id (UUID, required) – Project identifier

Example:

{
  "name": "get_project_team",
  "arguments": {
    "project_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Resources

org-structure

Organization structure overview with all departments.

URI: internal://org-structure

department-info

Detailed information about a specific department.

URI: internal://departments/{name}

Examples:

• internal://departments/Engineering
• internal://departments/Marketing

usage-guide

Guide on how to use the MCP server.

URI: internal://usage-guide

Authentication

The server supports multiple authentication methods:

Bearer Token (Recommended)

Include a Bearer token in the Authorization header:

cu