Skip to main content

​
What is MCP?

MCP (Model Context Protocol) is a standard protocol for AI applications to connect with external tools and services. An MCP server exposes tools via HTTP endpoints, allowing EigenData-CLI to:
  • Discover available tools and their specifications
  • Execute tools with parameters
  • Access environment state and user data
  • Manage sessions and state persistence
Using an MCP server lets you connect EigenData-CLI to your domain’s simulated environment, enabling realistic conversational data generation without writing custom integration code.

​
How MCP Servers Work

An MCP server acts as a bridge between EigenData-CLI and your domain environment. The typical workflow is:
  1. Discovery - EigenData-CLI queries the /tools endpoint to get available tools
  2. Environment Access - CLI calls get_environment_stats() and get_user_data() to understand the domain state
  3. Tool Execution - During data generation, the CLI executes domain-specific tools via POST requests
  4. State Management - The server maintains environment state across conversations

​
Configuring MCP Server

You can configure your MCP server URL at any time using /configure: 
eigendata> /configure mcp_server_url http://127.0.0.1:8000
EigenData-CLI accepts HTTP/HTTPS URLs, host:port, or domain:port formats.

​
Required MCP Tools

All MCP servers must implement these four essential tools to work with EigenData-CLI:

​
1. get_user_data

Retrieves user data from the environment, with optional filtering for related records. Parameters:
  • user_id (optional) - User ID to look up. If None, samples a random user
  • include_related (optional, default: true) - Whether to include related data from other database tables
Returns: Dictionary containing:
  • User profile information
  • Related data organized by table name (if include_related=true)
Example Response: 
{
  "user": {
    "user_id": "user_123",
    "name": "Alice Johnson",
    "email": "alice@example.com"
  },
  "documents": [
    {"id": "doc_1", "title": "Report", "author": "user_123"}
  ],
  "emails": [
    {"id": "email_1", "subject": "Meeting", "from": "user_123"}
  ]
}

​
2. get_environment_stats

Returns statistics about the current environment state, including database table counts and system status. Parameters: None Returns: Dictionary containing:
  • action_count - Number of actions performed
  • last_action - Most recent action name
  • initialized - Whether environment is initialized
  • Database statistics with table counts
Example Response: 
{
  "action_count": 42,
  "last_action": "CreateDocument",
  "initialized": true,
  "database": {
    "users": 10,
    "documents": 25,
    "emails": 18
  }
}

​
3. save_environment_state

Saves the current environment state to a file for persistence. Parameters:
  • path (optional) - File path to save state. If None, uses default path
Returns: Dictionary containing:
  • path - Path where state was saved
  • status - Success/failure status
Example Response: 
{
  "status": "success",
  "path": "/path/to/environment_state.json",
  "timestamp": "2024-01-15T10:30:00Z"
}

​
4. reset_environment

Resets the environment to its initial state, clearing all accumulated data. Parameters: None Returns: Dictionary containing:
  • status - Success/failure status
  • message - Confirmation message
Example Response: 
{
  "status": "success",
  "message": "Environment reset to initial state",
  "initialized": true
}

​
Optional MCP Tools

These tools enhance session management capabilities:

​
Session Management

  • create_session(session_id) - Create a new isolated session
  • delete_session(session_id) - Delete an existing session
  • list_sessions() - List all active sessions

​
MCP Server Endpoints

​
Tool Listing

Endpoint: GET /tools Returns all available tools with their specifications: 
{
  "tools": [
    {
      "name": "get_environment_stats",
      "description": "Get statistics about the current environment state",
      "input_schema": {
        "type": "object",
        "properties": {}
      }
    },
    {
      "name": "get_user_data",
      "description": "Get user data from the environment state",
      "input_schema": {
        "type": "object",
        "properties": {
          "user_id": {
            "type": "string",
            "description": "User ID to look up"
          },
          "include_related": {
            "type": "boolean",
            "description": "Include related data from other tables"
          }
        }
      }
    },
    {
      "name": "save_environment_state",
      "description": "Save the current environment state to a file",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "File path to save state"
          }
        }
      }
    },
    {
      "name": "reset_environment",
      "description": "Reset the environment to its initial state",
      "input_schema": {
        "type": "object",
        "properties": {}
      }
    }
  ]
}

​
Tool Execution

Endpoint: POST /mcp/tools/{tool_name} Executes a tool with the provided parameters: 
curl -X POST http://localhost:8000/mcp/tools/get_user_data \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user_123", "include_related": true}'
Response: 
{
  "status": "success",
  "data": {
    "user": { ... },
    "documents": [ ... ]
  }
}