Skip to content

API Reference

This document provides a complete reference for all API endpoints exposed by the pgEdge Natural Language Agent.

MCP JSON-RPC Endpoints

All MCP protocol methods are available via POST /mcp/v1:

initialize

Initializes the MCP connection.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "pgedge-nla-web",
      "version": "1.0.0-alpha2"
    }
  }
}

tools/list

Lists available MCP tools.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Response: 

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "query_database",
        "description": "Execute natural language queries against the database",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "Natural language query"
            }
          },
          "required": ["query"]
        }
      }
    ]
  }
}

tools/call

Calls an MCP tool.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "query_database",
    "arguments": {
      "query": "How many users are there?"
    }
  }
}

resources/list

Lists available MCP resources.

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/list"
}

resources/read

Reads an MCP resource.

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "resources/read",
  "params": {
    "uri": "pg://system_info"
  }
}

REST API Endpoints

GET /health

Health check endpoint (no authentication required).

Response: 

{
  "status": "ok",
  "server": "pgedge-postgres-mcp",
  "version": "1.0.0-alpha2"
}

GET /api/databases

Lists all databases accessible to the authenticated user.

Request: 

GET /api/databases HTTP/1.1
Authorization: Bearer <session-token>

Response: 

{
    "databases": [
        {
            "name": "production",
            "host": "localhost",
            "port": 5432,
            "database": "myapp",
            "user": "appuser",
            "sslmode": "require"
        },
        {
            "name": "analytics",
            "host": "analytics.example.com",
            "port": 5432,
            "database": "analytics",
            "user": "analyst",
            "sslmode": "require"
        }
    ],
    "current": "production"
}

Response Fields:

  • databases - Array of accessible database configurations
    • name - Unique name for this database connection
    • host - Database server hostname
    • port - Database server port
    • database - PostgreSQL database name
    • user - Database username
    • sslmode - SSL connection mode
  • current - Name of the currently selected database

Access Control:

  • Users only see databases listed in their available_databases configuration
  • API tokens only see their bound database (if configured)
  • In STDIO mode or with authentication disabled, all configured databases are visible

Implementation: internal/api/databases.go

POST /api/databases/select

Selects a database as the current database for subsequent operations.

Request: 

POST /api/databases/select HTTP/1.1
Content-Type: application/json
Authorization: Bearer <session-token>

{
    "name": "analytics"
}

Parameters:

  • name (required) - Name of the database to select

Success Response (200): 

{
    "success": true,
    "current": "analytics",
    "message": "Database selected successfully"
}

Error Responses:

Invalid request (400): 

{
    "success": false,
    "error": "Database name is required"
}

Database not found (404): 

{
    "success": false,
    "error": "Database not found"
}

Access denied (403): 

{
    "success": false,
    "error": "Access denied to this database"
}

API token bound to different database (403): 

{
    "success": false,
    "error": "API token is bound to a different database"
}

Notes:

  • Database selection is per-session (tied to the authentication token)
  • API tokens with a bound database cannot switch to a different database
  • Users can only select databases they have access to
  • The selected database persists for the duration of the session

Implementation: internal/api/databases.go

GET /api/user/info

Returns information about the authenticated user.

Request: 

GET /api/user/info HTTP/1.1
Authorization: Bearer <session-token>

Response: 

{
  "username": "alice"
}

Implementation: cmd/pgedge-pg-mcp-svr/main.go:454-511

POST /api/chat/compact

Smart chat history compaction endpoint. Intelligently compresses message history to reduce token usage while preserving semantically important context. Uses PostgreSQL and MCP-aware classification to identify anchor messages, important tool results, schema information, and error messages.

Request: 

POST /api/chat/compact HTTP/1.1
Content-Type: application/json

{
    "messages": [
        {"role": "user", "content": "Show me the users table"},
        {"role": "assistant", "content": "Here's the schema..."},
        ...
    ],
    "max_tokens": 100000,
    "recent_window": 10,
    "keep_anchors": true,
    "options": {
        "preserve_tool_results": true,
        "preserve_schema_info": true,
        "enable_summarization": true,
        "min_important_messages": 3,
        "token_counter_type": "anthropic",
        "enable_llm_summarization": false,
        "enable_caching": false,
        "enable_analytics": false
    }
}

Parameters:

  • messages (required): Array of chat messages to compact
  • max_tokens (optional): Maximum token budget, default 100000
  • recent_window (optional): Number of recent messages to preserve, default 10
  • keep_anchors (optional): Whether to keep anchor messages, default true
  • options (optional): Fine-grained compaction options
    • preserve_tool_results: Keep all tool execution results
    • preserve_schema_info: Keep schema-related messages
    • enable_summarization: Create summaries of compressed segments
    • min_important_messages: Minimum important messages to keep
    • token_counter_type: Token counting strategy - "generic", "openai", "anthropic", "ollama"
    • enable_llm_summarization: Use enhanced summarization (extracts actions, entities, errors)
    • enable_caching: Enable result caching with SHA256-based keys
    • enable_analytics: Track compression metrics

Response: 

{
    "messages": [
        {"role": "user", "content": "Show me the users table"},
        {"role": "assistant", "content": "[Compressed context: Topics: database queries, Tables: users, 5 messages compressed]"},
        ...
    ],
    "summary": {
        "topics": ["database queries"],
        "tables": ["users"],
        "tools": ["query_database"],
        "description": "[Compressed context: Topics: database queries, Tables: users, Tools used: query_database, 5 messages compressed]"
    },
    "token_estimate": 2500,
    "compaction_info": {
        "original_count": 20,
        "compacted_count": 8,
        "dropped_count": 12,
        "anchor_count": 3,
        "tokens_saved": 7500,
        "compression_ratio": 0.25
    }
}

Message Classification:

The compactor uses a 5-tier classification system:

  • Anchor - Critical context (schema changes, user corrections, tool schemas)
  • Important - High-value messages (query analysis, errors, insights)
  • Contextual - Useful context (keep if space allows)
  • Routine - Standard messages (can be compressed)
  • Transient - Low-value messages (short acknowledgments)

Implementation: internal/compactor/

Conversations API

The conversations API provides endpoints for managing chat history persistence. These endpoints are only available when user authentication is enabled.

GET /api/conversations

Lists conversations for the authenticated user.

Request: 

GET /api/conversations?limit=50&offset=0 HTTP/1.1
Authorization: Bearer <session-token>

Query Parameters:

  • limit (optional) - Maximum number of conversations to return (default: 50)
  • offset (optional) - Number of conversations to skip for pagination (default: 0)

Response: 

{
    "conversations": [
        {
            "id": "conv_abc123",
            "title": "Database schema exploration",
            "connection": "production",
            "created_at": "2025-01-15T10:30:00Z",
            "updated_at": "2025-01-15T11:45:00Z",
            "preview": "Show me the users table..."
        }
    ]
}

POST /api/conversations

Creates a new conversation.

Request: 

POST /api/conversations HTTP/1.1
Content-Type: application/json
Authorization: Bearer <session-token>

{
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "connection": "production",
    "messages": [
        {
            "role": "user",
            "content": "Show me the users table"
        },
        {
            "role": "assistant",
            "content": "Here's the schema for the users table..."
        }
    ]
}

Response (201 Created): 

{
    "id": "conv_abc123",
    "username": "alice",
    "title": "Show me the users table",
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "connection": "production",
    "messages": [...],
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
}

GET /api/conversations/{id}

Retrieves a specific conversation.

Request: 

GET /api/conversations/conv_abc123 HTTP/1.1
Authorization: Bearer <session-token>

Response: 

{
    "id": "conv_abc123",
    "username": "alice",
    "title": "Database schema exploration",
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "connection": "production",
    "messages": [
        {
            "role": "user",
            "content": "Show me the users table",
            "timestamp": "2025-01-15T10:30:00Z"
        },
        {
            "role": "assistant",
            "content": "Here's the schema...",
            "timestamp": "2025-01-15T10:30:05Z",
            "provider": "anthropic",
            "model": "claude-sonnet-4-20250514"
        }
    ],
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T11:45:00Z"
}

PUT /api/conversations/{id}

Updates a conversation (replaces all messages).

Request: 

PUT /api/conversations/conv_abc123 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <session-token>

{
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514",
    "connection": "production",
    "messages": [...]
}

Response: Same as GET response with updated data.

PATCH /api/conversations/{id}

Renames a conversation.

Request: 

PATCH /api/conversations/conv_abc123 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <session-token>

{
    "title": "New conversation title"
}

Response: 

{
    "success": true
}

DELETE /api/conversations/{id}

Deletes a specific conversation.

Request: 

DELETE /api/conversations/conv_abc123 HTTP/1.1
Authorization: Bearer <session-token>

Response: 

{
    "success": true
}

DELETE /api/conversations?all=true

Deletes all conversations for the authenticated user.

Request: 

DELETE /api/conversations?all=true HTTP/1.1
Authorization: Bearer <session-token>

Response: 

{
    "success": true,
    "deleted": 15
}

Implementation: internal/conversations/

LLM Proxy Endpoints

The LLM proxy provides REST API endpoints for chat functionality. See the LLM Proxy Guide for detailed documentation on these endpoints:

  • GET /api/llm/providers - List configured LLM providers
  • GET /api/llm/models?provider=<provider> - List available models
  • POST /api/llm/chat - Send chat request with tool support

See Also