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
- Change Transport Type to:
Streamable HTTP - Enter URL:
http://localhost:8000/mcp - Click Connect
3. Authentication
If MCP_AUTH_TOKEN is set in .env, all HTTP requests must include the token.
MCP_AUTH_TOKEN | Behavior |
|---|---|
| Not set | No authentication (open access) |
| Set | All requests require Authorization: Bearer <token> |
In MCP Inspector (HTTP)
- Select Transport Type:
Streamable HTTP - Enter URL:
http://localhost:8000/mcp - In the Headers section, add:
- Header Name:
Authorization - Header Value:
Bearer your-secret-token-here
- Header Name:
- 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_USERNAMEwith your actual Windows username. Find youruvpath with:where uv- Replace
your-secret-token-herewith the actualMCP_AUTH_TOKENfrom your.envfile- The
envvariables 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
| # | Tool | Input(s) | Purpose |
|---|---|---|---|
| 1 | resolve_user | name_or_email: str | Fuzzy find user → UUID |
| 2 | resolve_users_batch | names: list[str] | Batch fuzzy find |
| 3 | confirm_user | email: str | Exact email → UUID |
| 4 | confirm_users_batch | emails: list[str] | Batch exact email lookup |
| 5 | get_team_members | manager_identifier: str | Get all reports of manager |
| 6 | get_manager_of_user | user_identifier: str | Get user's manager(s) |
| 7 | get_user_by_uuid | user_uuid: str | UUID → full user details |
| 8 | resolve_user_in_team | name_or_email: str, manager_identifier: str | Scoped search within team |
| 9 | get_user_calendar_insights | user_identifier: str, date?, start_date?, end_date? | Complete calendar dashboard |
| 10 | query_user_meetings | user_identifier: str, start_date, end_date, filters... | Find/filter/sort meetings |
| 11 | get_meeting_details | event_id: str | Full meeting details with attendees |
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
name_or_email | string | ✅ | The user's name or email to resolve. Can be full name, partial name, email, or email prefix. |
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
names | list[string] | ✅ | List of names or emails to resolve. Maximum 50 items. |
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | ✅ | The exact email address to look up. |
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
emails | list[string] | ✅ | List of exact email addresses to look up. Maximum 50 items. |
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
manager_identifier | string | ✅ | Manager's email (preferred), UUID, or name. Email is most reliable for exact matches. |
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
user_identifier | string | ✅ | User's email (preferred) or UUID. |
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
user_uuid | string | ✅ | The user's UUID. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
name_or_email | string | ✅ | The user's name or email to search for. |
manager_identifier | string | ✅ | Manager's email (preferred) or UUID to scope the search. |
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:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
user_identifier | string | ✅ | - | User's email (preferred) or UUID. |
date | string | ❌ | - | Single date (YYYY-MM-DD) for day view. If provided, ignores start/end. |
start_date | string | ❌ | Last 7 days | Range start (YYYY-MM-DD). |
end_date | string | ❌ | Today | Range end (YYYY-MM-DD). Max range: 90 days. |
include_daily | boolean | ❌ | false | Include daily breakdown array. |
include_meetings | boolean | ❌ | false | Include list of actual meetings. |
Returns:
health: Status (healthy/warning/at_risk), concerns, positives, suggestionstime: Total meeting hours, focus hours, percentagesaverages: 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 seriesquality: Agenda coverage, average quality, large meetings countextremes: 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:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
user_identifier | string | ✅ | - | User's email (preferred) or UUID. |
start_date | string | ✅ | - | Start date (YYYY-MM-DD). |
end_date | string | ✅ | - | End date (YYYY-MM-DD). |
sort_by | string | ❌ | start_time | Sort field: start_time, duration, attendees, agenda_quality. |
order | string | ❌ | desc | Sort order: asc or desc. |
limit | integer | ❌ | 20 | Max results (max: 100). |
meeting_type | string | ❌ | - | Filter: 1_1, STANDUP, REVIEW, PLANNING, EXTERNAL, OTHER. |
is_external | boolean | ❌ | - | Filter by external flag. |
is_recurring | boolean | ❌ | - | Filter by recurring flag. |
has_agenda | boolean | ❌ | - | Filter by agenda presence. |
min_duration | integer | ❌ | - | Minimum duration in minutes. |
min_attendees | integer | ❌ | - | Minimum attendee count. |
search | string | ❌ | - | Title keyword search (case-insensitive). |
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
event_id | string | ✅ | The event ID from a previous query. |
Returns:
title: Meeting titleorganizer: Organizer's emailtime: Start, end, date, duration_minattendees: Total count, internal/external counts, full attendee listclassification: Meeting type, is_recurring, is_external, is_large_meetingquality: has_agenda, agenda_quality_index, agenda_signalsrecurring_info: series_id and instance_key (if recurring)tagged_priorities: Priority tags from title/description
Example:
get_meeting_details("abc123_20251212T100000Z")
