> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eigenai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Understand how MCP (Model Context Protocol) servers integrate with EigenData-CLI.

## 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`](/products/eigendata-cli/utility-commands/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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```bash theme={null}
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:**

```json theme={null}
{
  "status": "success",
  "data": {
    "user": { ... },
    "documents": [ ... ]
  }
}
```