ConfidentialMind MCP Agent

A flexible FastMCP client application for interacting with Model Context Protocol (MCP) servers to execute complex workflows. The agent supports both CLI and API modes with configurable transport options and includes an OpenAI API-compatible endpoint with comprehensive observability features.

Overview

The ConfidentialMind MCP Agent serves as a bridge between users and MCP servers, providing a unified interface for accessing various capabilities. It can:

• Process natural language queries and convert them into structured actions
• Connect to multiple MCP servers simultaneously
• Execute complex workflows with automatic error handling and replanning
• Maintain conversation context across sessions
• Operate as either a CLI tool or an API server with OpenAI compatibility
• Provide comprehensive observability with structured JSON logging and distributed tracing

Features

• Dual-Mode Operation:

  • CLI Mode: Run as a command-line tool using stdio transport for local development
  • API Mode: Run as a standalone server with an OpenAI-compatible API endpoint using streamable-HTTP transport

• ConfidentialMind Integration:

  • Automatic connector registration and URL discovery in stack deployment
  • Background polling for service URLs in production environments
  • Graceful operation even when services are not immediately available

• Flexible Transport Configuration:

  • Support for multiple MCP servers via configurable transports
  • Dynamic transport selection based on runtime mode
  • Automatic conversion of legacy SSE URLs to streamable-HTTP

• Robust Database Integration:

  • Automatic schema validation and creation
  • Connection pooling with reconnection logic
  • PostgreSQL-based session management

• Comprehensive Observability:

  • Structured JSON Logging: All logs compatible with OpenTelemetry Collector
  • Distributed Tracing: Request correlation across service boundaries
  • Performance Monitoring: Operation timing and metrics tracking
  • Error Context: Rich error logging with stack traces and operation context
  • Debug & Production Modes: Human-readable logs in development, JSON in production

• Intelligent Agent Workflow:

  • Multi-stage processing pipeline:
    1. Initialize context - discover available tools and resources
    2. Parse query - use LLM to plan actions
    3. Execute MCP actions - call tools on servers
    4. Evaluate results - check for errors and replan if needed
    5. Generate response - create final response based on results
  • Handles action failures with automatic replanning
  • Maintains conversation history for context

• OpenAI Compatibility:

  • Drop-in replacement for OpenAI's chat completions API
  • Session management via headers or cookies

Installation

# Clone the repository
git clone https://github.com/ConfidentialMind/confidentialmind-mcp-agent.git

# Navigate to project root
cd confidentialmind-mcp-agent

# Install uv (https://docs.astral.sh/uv/getting-started/installation/)
## MacOS:
brew install uv

## or
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment
uv venv --python 3.10

# Activate the virtual environment
source .venv/bin/activate

# Install dependencies
uv pip install -e .

Operational Modes

The agent supports two main operational modes:

1. Local Development Mode

In local development mode:

• Configuration loaded from .env file and environment variables
• Connection details retrieved from environment with pattern {CONFIG_ID}_URL and {CONFIG_ID}_APIKEY
• Services can be configured independently
• Human-readable logging for development

2. Stack Deployment Mode

In stack deployment mode:

• Automatically registers connectors with ConfigManager
• Discovers service URLs dynamically from the stack
• Continuously polls for URL changes in the background
• Operates gracefully even when services become available after startup
• Structured JSON logging for production observability

Configuration

Environment Variables

• MCP_SERVER_*: MCP servers in the format MCP_SERVER_NAME=url
• (Deprecating)AGENT_TOOLS_URL: Default URL of the MCP server (default: http://localhost:8080/mcp)
• DB_CONFIG_ID: Database connector config ID (default: DATABASE)
• LLM_CONFIG_ID: LLM service config ID (default: LLM)
• CONFIDENTIAL_MIND_LOCAL_CONFIG: Set to "False" for stack deployment mode
• DEBUG: Set to "true" for human-readable logs in development

Config File

You can provide a JSON configuration file with server definitions:

{
  "mcp_servers": {
    "postgres": "src/tools/postgres_mcp/__main__.py", // Using stdio in CLI mode
    "baserag": "src/tools/baserag_mcp/__main__.py"
  }
}

Or for API mode:

{
  "mcp_servers": {
    "postgres": "http://0.0.0.0:8080/mcp", // Using streamable-HTTP endpoint
    "other_server": "http://0.0.0.0:8081/mcp"
  }
}

Usage

The agent provides three main commands through its Typer CLI interface:

1. Query Mode

Run a single query in CLI mode:

# Basic query
python -m src.agent.main query "What tools are available?"

# With session ID
python -m src.agent.main query "Tell me more about table users" --session abc123

# With debug logging
python -m src.agent.main query "Why did the previous action fail?" --debug

# With custom config file
python -m src.agent.main query "Query the database" --config config.json

# With custom database and LLM connectors
python -m src.agent.main query "Complex query" --db CUSTOM_DB --llm CUSTOM_LLM

2. API Server Mode

Run as a standalone server with an OpenAI-compatible API endpoint:

# Start the API server with default settings
python -m src.agent.main serve

# Configure host and port
python -m src.agent.main serve --host 127.0.0.1 --port 3000

# With debug logging
python -m src.agent.main serve --debug

# With custom config file
python -m src.agent.main serve --config api_config.json

# With custom database and LLM connectors
python -m src.agent.main serve --db PRODUCTION_DB --llm GPT4

3. Clear Session History

Utility to clear the conversation history for a specific session:

# Clear history for a specific session ID
python -m src.agent.main clear-history abc123

# With custom database connector
python -m src.agent.main clear-history abc123 --db CUSTOM_DB

API Endpoints

Chat Completions Endpoint

POST /v1/chat/completions

Request format:

{
  "model": "cm-llm",
  "messages": [{ "role": "user", "content": "What tools are available?" }]
}

Response format:

{
  "id": "chatcmpl-123456",
  "object": "chat.completion",
  "created": 1692372149,
  "model": "cm-llm",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The available tools are..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

Health Check

GET /health

Response:

{
  "status": "healthy",
  "deployment_mode": "stack",
  "database": {
    "connected": true,
    "error": null
  },
  "llm": {
    "connected": true
  },
  "mcp_servers": {
    "count": 2,
    "servers": ["postgres", "otherServer"]
  },
  "timestamp": "2023-08-18T12:34:56.789Z"
}

Observability Features

The system includes comprehensive observability with structured logging and distributed tracing:

Structured JSON Logging

All logs are output in JSON format compatible with OpenTelemetry Collector:

{
  "timestamp": "2024-01-15T10:30:45.123Z",
  "level": "info",
  "logger": "agent.core",
  "event": "Starting agent workflow",
  "event_type": "agent.workflow.start",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "span_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "session_id": "user-session-123",
  "duration_ms": 150.5,
  "success": true,
  "data": {
    "query_preview": "What tools are available?",
    "action_count": 3
  }
}

Distributed Tracing

Request traces flow across all service boundaries:

• Agent API → MCP Servers → Backend Services
• Automatic trace context propagation via HTTP headers
• Parent-child span relationships
• Performance timing for all operations

Event Types

Consistent event taxonomy for log analysis:

• agent.workflow.* - Agent processing stages
• mcp.transport.* - MCP client operations
• sql.query.* - Database operations
• tool.execution.* - Tool invocations
• health.check.* - Health monitoring

For complete observability documentation, see guides/observability.md.

Session Management

Session IDs can be provided in one of these ways:

1. In the CLI using the --session option
2. In the API via the X-Session-ID header
3. Via a session_id cookie in the API
4. Automatically generated if not provided

Agent Workflow

The agent follows a multi-stage workflow for processing queries:

1. Initialize Context:

   • Discover available tools and resources from MCP servers
   • Set up execution context with available capabilities

2. Parse Query:

   • Use LLM to understand the user's intent
   • Create a plan with specific actions to execute
   • Determine which MCP servers and tools are needed

3. Execute MCP Actions:

   • Call tools on appropriate MCP servers
   • Process results and handle any errors
   • Track execution state for complex workflows

4. Evaluate Results:

   • Check if actions were successful
   • Identify errors or unexpected results
   • Determine if replanning is necessary

5. Replan Actions (if needed):

   • Use LLM to generate a revised plan based on errors
   • Adjust subsequent actions to recover from failures
   • Create new approach to solve the original intent

6. Generate Response:

   • Create a coherent response from all gathered information
   • Format data appropriately for the user
   • Include error explanations if things went wrong

Available MCP Servers

The repository includes the following MCP servers:

PostgreSQL MCP Server

A FastMCP server providing read-only access to PostgreSQL databases. It allows:

• Schema inspection via the postgres://schemas resource
• SQL query execution via the execute_sql tool (read-only)
• Comprehensive observability with structured logging and performance tracking

For more details on the PostgreSQL MCP server, see src/tools/postgres_mcp/README.md.

BaseRAG MCP Server

A FastMCP server providing access to BaseRAG's retrieval-augmented generation capabilities:

• Context retrieval from knowledge bases
• Content access by ID
• RAG-enhanced chat completions
• Full observability integration

For more details on the BaseRAG MCP server, see src/tools/baserag_mcp/README.md.

Connecting MCP Servers

To connect the agent to an MCP server:

# Start the PostgreSQL MCP server
python -m src.tools.postgres_mcp

# Then start the agent in API mode, configuring the PostgreSQL server
python -m src.agent.main serve --config postgres_config.json

Example postgres_config.json:

{
  "mcp_servers": {
    "postgres": "http://localhost:8080/mcp"
  }
}

Docker Support

Docker configurations are provided for both the agent and MCP servers:

# Build the agent container
docker build -f docker/agent.Dockerfile -t confidentialmind-mcp-agent .

# Build the PostgreSQL MCP server container
docker build -f docker/postgres-mcp.Dockerfile -t confidentialmind-postgres-mcp .

# Run the PostgreSQL MCP server
docker run -p 8080:8080 -e PG_HOST=host.docker.internal confidentialmind-postgres-mcp

# Run the agent in API mode
docker run -p 8000:8080 -e AGENT_TOOLS_URL=http://host.docker.internal:8080/mcp confidentialmind-mcp-agent

Development

Prerequisites

• Python 3.10+
• PostgreSQL database
• FastMCP-compatible MCP servers
• Access to confidentialmind_core SDK

Architecture

The agent uses a modular architecture with these key components:

• ConnectorConfigManager: Manages connection configuration for stack deployment
• TransportManager: Handles transport configuration and client management
• Agent: Core workflow logic for executing MCP-based queries
• Database: Session management and history storage
• LLMConnector: Interface to language model services
• Shared Logging: Structured logging and distributed tracing

Running Tests

To test the API mode:

• Initialize the Postgres MCP server: python -m src.tools.postgres_mcp
• Initialize the Baserag MCP server: python -m src.tools.baserag_mcp
• Initialize the agent in API mode: python -m src.agent.main serve
• Run the test: python -m tests.test_agent_api

To test the CLI mode:

• Run the test: python -m tests.test_agent_cli

Debugging

Enable debug logging with the --debug flag in any command mode:

python -m src.agent.main query "Debug this" --debug
python -m src.agent.main serve --debug

This enables human-readable console output with trace information for development.

Additional Documentation

• For more details on the agent implementation, see src/agent/README.md
• For PostgreSQL MCP server documentation, see src/tools/postgres_mcp/README.md
• For BaseRAG MCP server documentation, see src/tools/baserag_mcp/README.md
• For observability features and JSON logging, see guides/observability.md
• For guidance on building MCP servers with observability, see guides/mcp_server_guide.md
• For details on ConfidentialMind connection management, see guides/confidentialmind.md
• For a guide on containerizing MCP servers, see guides/mcp_containerization.md

Resilience Features

The agent includes several resilience features:

• Connection Retries: Automatic reconnection with exponential backoff
• Background Polling: Continuous polling for URL changes in stack mode
• Graceful Degradation: Operation with partial service availability
• Error Recovery: Replanning logic to handle action failures
• Stateless Fallback: Can operate without database connection if needed
• Comprehensive Monitoring: Full observability for troubleshooting and performance analysis