MCP Census Server

🚀 MCP Census Server

A powerful Model Context Protocol (MCP) server for accessing U.S. Census Bureau data via JSON-RPC over HTTP.

✨ Features

• Support for JSON-RPC 2.0 (single and batch requests)
• Request/response validation using Pydantic models
• Caching of Census API responses (expiration time: 5 minutes)
• Structured logging (via Python logging)
• API key authentication via the X-API-Key header
• Health check endpoint (/health)
• Interactive API documentation (Swagger UI accessible at /docs)
• MCP methods:
  • initialize: Negotiate protocol version and features
  • notifications/initialized: Client readiness notification
  • tools/list: List available tools (census/get)
  • tools/call: Call census/get to retrieve Census Bureau data

🚀 Quick Start

1. Clone the repository and navigate to the directory:

   git clone https://github.com/kaman1/mcp_census_server.git
   cd mcp_census_server
   

2. Copy the environment variable template and set your keys:

   cp .env.example .env
   # Edit .env:
   # CENSUS_API_KEY=<your_census_api_key>
   # SERVER_API_KEY=<your_mcp_server_secret_key>
   

3. Install the dependencies:

   pip install -r requirements.txt
   

4. Start the server:

   uvicorn app:app --host 0.0.0.0 --port 8000 --reload
   

5. Send JSON-RPC requests to http://localhost:8000/ with the header X-API-Key: <SERVER_API_KEY>.

Example tools/list call:

curl -X POST http://localhost:8000/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $SERVER_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

🛠️ Development

• Testing: pytest
• Formatting: black .
• Imports: isort .
• Code checking: flake8 .
• CI pipeline configuration is in .github/workflows/ci.yml

📚 Documentation

• Architecture: docs/architecture.md
• Usage examples: docs/usage.md
• Authentication: docs/authentication.md
• Style documentation (MDX + Mintlify):

  npm install
  npm run serve:docs
  

📄 Hosting Documentation

You can publish these documents via GitHub Pages:

1. In your GitHub repository, go to Settings > Pages.
2. Under Source, select the main branch and the /docs folder.
3. Click Save.

The documentation will be available at:

https://<username>.github.io/mcp_census_server/

You can set it as the project website in the About section of the repository.

💻 Client Application

The client/ directory contains a Next.js-based MCP client that can interact with this server.

1. Switch to the client folder:

   cd client
   

2. Copy the example environment file and fill in your keys and server URL:

   cp .env.example .env.local
   # Set OPENAI_API_KEY, MCP_SERVER_URL (e.g., https://your-server), SERVER_API_KEY
   

3. Install the dependencies and start the development server:

   npm install
   npm run dev
   

4. Open http://localhost:3000 to use the client UI.

⚡ Quick Start Script

You can configure the environment and run the server and client simultaneously:

chmod +x start.sh
./start.sh

This will prompt you to enter all the required keys and run the MCP server and client concurrently.