MCP PostgreSQL Server

A FastMCP server for user name resolution with PostgreSQL backend.

Prerequisites

pip install -r requirements.txt

Ensure .env file contains database credentials and auth token:

DB_HOST=your_host
DB_PORT=5432
DB_NAME=your_database
DB_USER=your_user
DB_PASSWORD=your_password

# Authentication (optional for STDIO, recommended for HTTP)
MCP_AUTH_TOKEN=your-secret-token-here

1. Running with STDIO Transport

a) Development Mode (with MCP Inspector)

fastmcp dev server.py

This launches MCP Inspector automatically in your browser for interactive testing.

b) Direct Mode

fastmcp run server.py

Or:

python server.py

2. Running with HTTP Transport

a) Start the HTTP Server

python server.py --http

Server starts at: http://localhost:8000/mcp

b) Launch MCP Inspector

Open a new terminal:

npx @modelcontextprotocol/inspector

c) Connect to Server in MCP Inspector

1. Change Transport Type to: Streamable HTTP
2. Enter URL: http://localhost:8000/mcp
3. Click Connect

3. Authentication

If MCP_AUTH_TOKEN is set in .env, all HTTP requests must include the token.

In MCP Inspector (HTTP)

1. Select Transport Type: Streamable HTTP
2. Enter URL: http://localhost:8000/mcp
3. In the Headers section, add:
   • Header Name: Authorization
   • Header Value: Bearer your-secret-token-here
4. Click Connect

Without the correct token, you'll receive 401 Unauthorized.

In LangChain/LangGraph

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "user_resolver": {
        "transport": "streamable_http",
        "url": "http://localhost:8000/mcp",
        "headers": {
            "Authorization": "Bearer your-secret-token-here"
        }
    }
})

In FastMCP Client (Python)

from fastmcp import Client
from fastmcp.client.auth import BearerAuth

client = Client(
    "http://localhost:8000/mcp",
    auth=BearerAuth("your-secret-token-here")
)

4. Claude Desktop Integration (Free Version)

Claude Desktop free version only supports STDIO transport. Use the proxy server to bridge to your HTTP server.

Architecture

Claude Desktop ←→ proxy_server.py (STDIO) ←→ server.py (HTTP)

Setup Steps

Step 1: Start the HTTP Server

python server.py --http

Step 2: Run the Proxy Server (Optional - for manual testing)

C:\Users\shubhammishra_remote\AppData\Local\Programs\Python\Python310\Scripts\uv run proxy_server.py

Step 3: Configure Claude Desktop

Edit the Claude Desktop config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "Efforti Name Resolver": {
      "command": "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\Python\\Python310\\Scripts\\uv",
      "args": [
        "--directory",
        "D:\\MemoryCloud\\mcp-development",
        "run",
        "proxy_server.py"
      ],
      "env": {
        "MCP_SERVER_URL": "http://localhost:8000/mcp",
        "MCP_AUTH_TOKEN": "your-secret-token-here"
      },
      "transport": "stdio"
    }
  }
}

Important:

• Replace YOUR_USERNAME with your actual Windows username. Find your uv path with: where uv
• Replace your-secret-token-here with the actual MCP_AUTH_TOKEN from your .env file
• The env variables are required for the proxy to connect to the HTTP server

Step 4: Restart Claude Desktop

Close and reopen Claude Desktop. Look for the hammer icon (🔨) in the input box.

Step 5: Test

Ask Claude:

"Use the resolve_user tool to find shubham mishra"

Available Tools

Quick Reference

Category 1: User Resolution Tools

1. resolve_user

Description:
Resolve a user name or email to their UUID using fuzzy matching. Returns the user's UUID if confidently resolved, or asks for verification/disambiguation if uncertain.

Input Parameters:

Example:

resolve_user("john doe")
resolve_user("john.doe@company.com")
resolve_user("joh")  # partial match

2. resolve_users_batch

Description:
Resolve multiple user names or emails to their UUIDs in a single call. Efficiently processes a batch and returns results for each input.

Input Parameters:

Example:

resolve_users_batch(["john doe", "jane smith", "bob@company.com"])

3. confirm_user

Description:
Confirm a user by their exact email and get their UUID. Use this after verification/disambiguation when the user has confirmed which email is correct.

Input Parameters:

Example:

confirm_user("john.doe@company.com")

4. confirm_users_batch

Description:
Confirm multiple users by their exact emails and get their UUIDs. More efficient than calling confirm_user multiple times.

Input Parameters:

Example:

confirm_users_batch(["john@company.com", "jane@company.com", "bob@company.com"])

Category 2: Team Management Tools

5. get_team_members

Description:
Get all team members under a specific manager. Retrieves all users who report to the specified manager (including users under them as remote manager).

Input Parameters:

Example:

get_team_members("john.manager@company.com")
get_team_members("550e8400-e29b-41d4-a716-446655440000")
get_team_members("John Manager")  # name search

6. get_manager_of_user

Description:
Get the manager(s) of a specific user. Returns both primary manager and remote manager if applicable.

Input Parameters:

Example:

get_manager_of_user("employee@company.com")
get_manager_of_user("550e8400-e29b-41d4-a716-446655440000")

7. get_user_by_uuid

Description:
Get complete user details by their UUID. Use this for quick lookups when you already have the UUID from a previous resolution.

Input Parameters:

Example:

get_user_by_uuid("550e8400-e29b-41d4-a716-446655440000")

8. resolve_user_in_team

Description:
Resolve a user name/email within a specific manager's team only. This is a SCOPED search that only returns users who report to the specified manager. Use for security/relevance when searches should stay within team boundaries.

Input Parameters:

Example:

resolve_user_in_team("john", "team.manager@company.com")
resolve_user_in_team("john.doe@company.com", "550e8400-e29b-41d4-a716-446655440000")

Category 3: Calendar Insights Tools

9. get_user_calendar_insights

Description:
Get comprehensive calendar insights for a user - the complete dashboard. Provides health assessment, metrics, statistical extremes (longest/shortest/largest meetings), recurring meeting analysis, and quality metrics.

Input Parameters:

Returns:

• health: Status (healthy/warning/at_risk), concerns, positives, suggestions
• time: Total meeting hours, focus hours, percentages
• averages: Per-day metrics (meeting load %, focus minutes, meetings/day)
• by_type: Breakdown by meeting type (1:1, standup, review, planning, external)
• recurring: Recurring meeting count, percentage, top series
• quality: Agenda coverage, average quality, large meetings count
• extremes: Longest/shortest/largest meetings, busiest/lightest days

Example:

get_user_calendar_insights("john@company.com", date="2025-12-12")
get_user_calendar_insights("john@company.com", start_date="2025-12-01", end_date="2025-12-31")
get_user_calendar_insights("john@company.com", include_meetings=True)

10. query_user_meetings

Description:
Query user's meetings with flexible filtering and sorting. Use this to find specific meetings, get sorted lists (longest, shortest, largest), filter by criteria, or search by title keyword.

Input Parameters:

Example:

# Find longest meeting
query_user_meetings("john@company.com", "2025-12-01", "2025-12-31", sort_by="duration", order="desc", limit=1)

# Find shortest meeting
query_user_meetings("john@company.com", "2025-12-01", "2025-12-31", sort_by="duration", order="asc", limit=1)

# Search by title
query_user_meetings("john@company.com", "2025-12-01", "2025-12-31", search="sprint planning")

# Filter recurring meetings
query_user_meetings("john@company.com", "2025-12-01", "2025-12-31", is_recurring=True)

# Find meetings without agenda
query_user_meetings("john@company.com", "2025-12-01", "2025-12-31", has_agenda=False)

# Large meetings (>10 attendees)
query_user_meetings("john@company.com", "2025-12-01", "2025-12-31", min_attendees=10)

11. get_meeting_details

Description:
Get full details of a specific meeting. Use the event_id from query_user_meetings or get_user_calendar_insights to get complete information including attendee list, organizer, and agenda quality signals.

Input Parameters:

Returns:

• title: Meeting title
• organizer: Organizer's email
• time: Start, end, date, duration_min
• attendees: Total count, internal/external counts, full attendee list
• classification: Meeting type, is_recurring, is_external, is_large_meeting
• quality: has_agenda, agenda_quality_index, agenda_signals
• recurring_info: series_id and instance_key (if recurring)
• tagged_priorities: Priority tags from title/description

Example:

get_meeting_details("abc123_20251212T100000Z")