tpushkarsingh/custom_mcp_server

MCP server (local-mcp)

This repository implements a pure FastMCP-based server that exposes database introspection and domain-specific functions as "tools". The server uses FastMCP to register Python functions as tools that can be discovered and invoked by MCP clients.

This README explains what the server provides, how to configure it, and how MCP clients can discover and use the tools.

What this server is

• A pure FastMCP server that exposes a tool registry.
• Tools are Python functions registered via FastMCP decorators.
• The repository includes database helpers in app/db.py (introspection and domain helpers for departments, employees and job bands).
• These helpers are registered as tools in app/mcp_server.py using FastMCP's tool registration system.

The intended usage is for any MCP client that understands the FastMCP protocol to discover and call the tools.

Repository layout (relevant files)

• app/mcp_server.py — FastMCP server implementation and tool registrations
• app/db.py — Postgres helpers (introspection + domain methods like list_employees)
• db-init/init.sql — DB initialization SQL (domain tables and sample data)
• test_server.py — small script used to validate DB connectivity and queries

Configuration

Configuration is via environment variables. Defaults are set for local development; change them as needed.

• DB_HOST — database host (default: localhost)
• DB_PORT — database port (default: 5432)
• DB_NAME — database name (default: mcpdb)
• DB_USER — database user (default: pguser)
• DB_PASS — database password (default: pgpass)

Set them in your shell or in your process manager before starting the server. Example:

export DB_HOST=localhost DB_PORT=5432 DB_NAME=mcpdb DB_USER=pguser DB_PASS=pgpass

If you are using the included docker-compose.yml with the db service, the db-init/ scripts are applied to the database on first initialization of the postgres container. If you change db-init/init.sql after the DB has already been initialized, re-create the DB container or apply the SQL manually against the running DB.

Using the FastMCP Server

The server is implemented as a pure FastMCP server, which means it can be used by any MCP client that understands the FastMCP protocol. The server provides:

1. Tool Discovery - Clients can query available tools and their metadata
2. Tool Invocation - Clients can invoke tools with arguments
3. Result Handling - Results are returned directly to the client

The tools are automatically registered when the module is imported, and FastMCP handles all the communication protocol details.

Tool Usage

Tools can be discovered and invoked through any FastMCP-compatible client. Each tool is a Python function with:

• A unique name
• Optional documentation
• Type-annotated arguments
• JSON-serializable return values

Example usage in Python with FastMCP client:

from fastmcp import FastMCPClient

client = FastMCPClient("postgres-mcp-server")
tools = client.list_tools()  # discover available tools

# Invoke a tool
result = client.invoke("employees", department_id=1)
print(result)

Using with VS Code

VS Code can interact with this FastMCP server through any FastMCP-compatible extension or client. The tools are automatically discovered and can be invoked directly through the FastMCP protocol.

When using a FastMCP-aware extension:

1. Configure the extension to connect to this FastMCP server
2. Browse available tools through the extension's interface
3. Invoke tools with arguments and receive results

Example tool invocation format:

# Example: Filter employees by department and job band
result = client.invoke("employees_filtered", 
                      department_id=1, 
                      job_band_id=2)

Tools return JSON-serializable Python objects that can be easily handled by any client.

Important notes & troubleshooting

• The database DDL and sample data used locally live in db-init/init.sql. Those statements are applied automatically only when a fresh Postgres container is created (docker-compose first-start). If you modify db-init/init.sql after the DB already exists, either:

  • Recreate the DB container so initialization runs again, or
  • Connect to the running DB and apply the SQL manually (psql or a DB client).

• If tools fail with errors like relation "XXX" does not exist, confirm the DB schema exists and the DB_* env vars point to the correct database.

• The MCP wrapper accepts and returns JSON-serializable results only. Tool functions should return simple Python primitives (dicts, lists, strings, numbers) or objects that are JSON serializable (e.g., using psycopg2 RealDictCursor results are dict-like and serializable).

Security

• This repository is intended for local development. When deploying, use FastMCP's built-in security features for authentication and authorization.

Extending the server

• To register a new tool, add a function in app/mcp_server.py and decorate it with @mcp.tool
• Use mcp.expose_module(your_module) to expose all public functions from a module automatically
• Add docstrings and type hints to improve tool discoverability and usage

Next steps (suggested)

• Add example FastMCP client code showing tool discovery and invocation
• Add unit tests using FastMCP's testing utilities
• Add more detailed tool documentation and argument schemas
• Implement additional database introspection tools

The server is now a pure FastMCP implementation, making it easier to maintain and integrate with any FastMCP-compatible client.