MCP Gateway and Inspector

A modular Microservice Communication Protocol (MCP) Gateway package for wrapping GraphQL APIs with standardized tracing, authentication, and error handling. Includes a full-featured web inspector for testing and monitoring.

Features

MCP Gateway Package

• Modular Design: Reusable Python package that can be installed via pip or used standalone

• Tracing: Automatic correlation ID generation and propagation

• Authentication: Bearer token validation middleware

• Error Handling: Standardized MCP error codes and responses

• GraphQL Proxy: Seamless proxying to backend GraphQL services

MCP Inspector Web App

• Request Builder: Visual GraphQL query editor

• Response Viewer: Formatted JSON response display with error highlighting

• Request History: Track and replay previous requests

• Environment Management: Switch between dev/staging/prod environments

• Request Templates: Save and reuse common queries

• Export/Import: Share requests as JSON files

• Correlation ID Tracking: View and copy correlation IDs for debugging

Installation

Python Package

Inspector Web App

Configuration

Copy .env.example to .env and configure:

Key configuration options:

• TARGET_GRAPHQL_URL: Backend GraphQL API endpoint

• PORT: Gateway server port (default: 8080)

• ENABLE_AUTH: Enable/disable authentication (default: true)

• LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR)

Usage

Running the Gateway

The gateway will be available at http://localhost:8080

Running Mock Backend (for Testing)

If you don't have a real GraphQL backend, you can use the included mock backend for testing:

The mock backend will be available at http://localhost:8081 and supports common GraphQL queries like:

• query { hello }

• query { user(id: "1") { id name email } }

• query { users { id name email } }

• mutation { createUser(input: {name: "John", email: "john@example.com"}) { id } }

Important:

• Make sure the mock backend is running before starting the gateway

• Test the backend: curl http://localhost:8081/health

• If you get "Connection refused", the mock backend is not running

• See QUICKSTART.md for detailed troubleshooting

Running MCP Server for LLM Integration

The CRM Employee Management MCP Server (Model Context Protocol) exposes CRM functions as tools that LLMs can use:

MCP Server Tools:

• list_employees - List/search employees with filters

• get_employee - Get employee details by ID

• create_employee - Create new employee

• update_employee - Update employee information

• delete_employee - Delete employee (soft delete)

• search_employees - Search employees by name, email, etc.

• get_employee_stats - Get employee statistics

• get_departments - List all departments

Configuration: See MCP_SETUP.md for detailed setup instructions for Claude Desktop, Cursor, and other MCP-compatible clients.

Example Usage with LLM: Once connected to Claude Desktop or Cursor, you can use natural language:

• "List all employees in the Engineering department"

• "Show me employee statistics"

• "Create a new employee named John Doe in Sales"

• "Search for employees with 'engineer' in their position"

Running CRM REST API Server

The CRM Employee Management REST API Server is a comprehensive REST API server for managing employee data:

The CRM server will be available at http://localhost:8083 and provides:

Employee Management Endpoints:

• GET /api/employees - List all employees (with filtering, pagination, sorting)

• GET /api/employees/{id} - Get employee details

• POST /api/employees - Create new employee

• PUT /api/employees/{id} - Update employee

• DELETE /api/employees/{id} - Delete employee (soft delete)

• GET /api/employees/search?q={query} - Search employees

• GET /api/employees/department/{dept} - Get employees by department

• GET /api/employees/stats - Get employee statistics

• GET /api/departments - List all departments

Example Employee Data Model:

Running the Inspector

The inspector will be available at http://localhost:3000 and includes:

• GraphQL Inspector: Test GraphQL queries and mutations

• CRM Manager: Full-featured employee management interface with:

  • Employee list with search and filtering

  • Add/Edit/Delete employees

  • Department-based filtering

  • Employee statistics dashboard

Quick Start - All Services at Once

To start all four services (Mock Backend, Gateway, CRM MCP Server, and Inspector) with a single command:

This script will:

• Check dependencies and port availability

• Start all services in separate terminal windows

• Display service URLs and useful endpoints

• Show informative status messages

Note: On macOS, the script opens new Terminal windows. On Linux, it uses gnome-terminal.

Services Started:

1. Mock Backend (port 8081) - GraphQL test backend

2. Gateway (port 8080) - MCP Gateway with REST and GraphQL proxy

3. CRM MCP Server (port 8083) - Employee management REST API

4. Inspector (port 3000) - Web UI for testing and management

Stopping All Services

To stop all services and free up ports:

This script will stop all running services (Mock Backend, Gateway, CRM MCP Server, Inspector) and verify that ports 8081, 8080, 8083, and 3000 are free.

Using the MCP Package in Your Project

As a Package

Standalone Module

Copy the mcp/ directory to your project and import as needed.

API Endpoints

Gateway Endpoints

• POST /graphql - Proxy GraphQL requests

• POST /mcp/proxy - Dynamic GraphQL proxy (for Inspector)

• POST /mcp/rest-proxy - REST API proxy (supports GET, POST, PUT, DELETE, PATCH)

• GET /health - Health check endpoint

Request Format

Authentication

Include Bearer token in Authorization header:

Error Codes

• MCP-401: Authentication failed

• MCP-503: Backend service unavailable

• BACKEND-ERROR: Backend service error

• MCP-500: Internal server error

Project Structure

Testing

Test the Gateway

Using the Inspector

1. Start the gateway and inspector

2. Open http://localhost:3000 in your browser

3. Configure an environment (default: http://localhost:8080)

4. Enter your GraphQL query

5. Add authentication token if required

6. Click "Send Request"

7. View response, correlation ID, and timing information

Development

Python Development

Inspector Development

MCP Server for LLM Integration

This project includes a Model Context Protocol (MCP) server that allows LLMs (like Claude Desktop, Cursor) to interact with the CRM system through natural language.

Quick Start

1. Install MCP SDK:

2. Start the MCP Server:

3. Configure Claude Desktop or Cursor:

   • See MCP_SETUP.md for detailed instructions

   • Add the MCP server configuration pointing to crm_mcp_server_mcp.py

Available Tools

The MCP server exposes 8 tools for comprehensive CRM management:

• list_employees - List/search employees with optional filtering by department, status, or search query

• get_employee - Get detailed information about a specific employee by ID

• create_employee - Create a new employee record in the CRM system

• update_employee - Update an existing employee's information

• delete_employee - Delete an employee (soft delete - sets status to 'terminated')

• search_employees - Search for employees by name, email, position, or department

• get_employee_stats - Get statistics and analytics about employees

• get_departments - Get a list of all departments in the organization

Example Usage

Once connected to Claude Desktop or Cursor, you can use natural language:

The LLM will automatically use the appropriate MCP tools to fulfill your requests.

Data Store Integration

The MCP server uses the same data store as the REST API server (crm_mcp_server.py). Both servers share the same employees_db dictionary, so changes made through one interface are visible in the other.

Documentation

For complete setup instructions, see MCP_SETUP.md.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.