MCP Server Demo: OAuth, TypeScript & Firestore Patterns

This repository provides a stripped-down, illustrative implementation of a Model Context Protocol (MCP) server. It showcases the architectural patterns, security considerations (OAuth 2.0), and development practices (TypeScript, Firestore, Zod) detailed in our accompanying article:

➡️ Read the full story: "Building a Production-Ready MCP Server with OAuth, TypeScript, and Our Battle Scars"

This demo focuses on the MCP Resource Server component and assumes you have a separate OAuth 2.0 Authorization Server.

Update: MCP SDK version 1.12.0 introduced the Authorization Server Metadata (/.well-known/oauth-authorization-server) support and removes the need to proxy the oauth calls through the MCP resource server.

Purpose

This repository is intended as a learning resource to:

• Demonstrate a practical implementation of an MCP server using the TypeScript MCP SDK.
• Illustrate how to integrate OAuth 2.0 for securing tool calls.
• Showcase patterns for managing workspace context and multi-tenancy.
• Provide examples of using Zod for schema definition and validation.
• Offer insights into structuring tools, using Higher-Order Components (HOCs) for common logic, and interacting with Firestore.

This is NOT a production-ready, plug-and-play server for all use cases. It omits specific business logic and assumes a pre-existing OAuth Authorization Server.

Key Features & Patterns Demonstrated

• MCP TypeScript SDK Integration: Core server setup and tool registration.
• OAuth 2.0 Token Validation: Securely handling Bearer tokens (via the SDK middleware).
• Workspace Context Management:
  • Explicit workspace_id in tool arguments.
  • withWorkspaceAccess Higher-Order Component (HOC) for authentication and workspace authorization.
• Firestore Integration:
  • Fetching user data, OAuth token information (conceptual), and tool-specific data.
  • Using Firestore emulators for local development and testing.
• Zod for Schemas & Validation: Defining input schemas for tools and leveraging Zod for runtime validation.
• Type-Safe Development: Leveraging TypeScript for robust code.
• Utility Functions: Examples of fetchResourceList for DRY data fetching.
• Standardized Error Handling: Using throw new Error() for clear error propagation.
• Example Tool Structures: Basic tool definitions showcasing the patterns.
• Environment Variable Configuration: For database and OAuth settings.

Architectural Overview

This demo represents the MCP Resource Server. It expects OAuth 2.0 Bearer tokens issued by a separate OAuth Authorization Server.

[Client / LLM with MCP Client SDK]
       |
       | (HTTPS Request with Bearer Token)
       v
[This MCP Resource Server (Node.js / TypeScript)]
       |  1. MCP SDK Middleware (parses request, extracts token)
       |  2. `withWorkspaceAccess` HOC
       |     a. Using the userId associated with the token
       |     b. Validates the user can access the workspace_id in the request
       |  3. Tool Handler Execution (interacts with Firestore based on validated context)
       |
       v
[Google Firestore (Database)]

The OAuth Authorization Server (which you would provide or have existing) is responsible for:

• Authenticating users.
• Issuing OAuth tokens (Access Tokens, Refresh Tokens).
• Managing OAuth clients (Dynamic Discovery).

This Resource Server then validates the tokens received from clients.

Prerequisites

• Node.js (v18.x or later recommended)
• npm or yarn
• Access to a Google Cloud Project with Firestore enabled OR Google Cloud SDK configured for Firestore Emulator.
• An existing OAuth 2.0 Authorization Server.

Getting Started

1. Clone the repository:

   git clone https://github.com/portal-labs-infrastructure/mcp-server-blog
   cd mcp-server-blog
   

2. Install dependencies:

   npm install
   # or
   yarn install
   

3. Set up Environment Variables: Copy the .env.example file to a new file named .env:

   cp .env.example .env
   

   Now, edit .env and fill in the required configuration values:

   # Firestore Configuration
   # If using Firestore Emulator, these might not all be strictly needed,
   # but ensure your gcloud CLI is configured or provide necessary emulator host.
   PROJECT_ID="your-gcp-project-id"
   # FIRESTORE_EMULATOR_HOST="localhost:8081" # Uncomment if using emulator and not relying on gcloud config
   
   # OAuth 2.0 Configuration (for this Resource Server to validate tokens)
   # This depends on your OAuth Authorization Server's setup.
   OAUTH_ISSUER_URL="https_your_auth_server_com"
   
   # MCP Server Configuration
   BASE_URL="http://localhost:8080" # URL this server is accessible at
   

   Important: The OAuth configuration is crucial. This server needs to know how to validate tokens issued by your Authorization Server. Consult your Auth Server's documentation.

4. (Optional) Seed Firestore Data: If you have seed scripts or want to manually add some sample users, OAuth tokens (matching what your Auth server would issue), and workspace data to your Firestore instance/emulator, do so now. This will make testing the tools more meaningful.

Running the Server

• Development Mode (with Nodemon for auto-restarts):

  npm run dev
  

• Production Mode: bash npm run build npm start The server will typically start on http://localhost:8080 (or the port specified in .env).

Running with Firestore Emulator

1. Ensure Google Cloud SDK is installed and configured.
2. Start the Firestore emulator in a separate terminal:

   gcloud emulators firestore start --host-port=localhost:8081
   

   (Adjust port if needed and update FIRESTORE_EMULATOR_HOST in .env or ensure your application automatically detects it via gcloud environment variables).
3. Run the MCP server as described above. It should connect to the emulator.

Key Patterns & Concepts Demonstrated in Code

Look for these patterns in the src directory:

• src/index.ts: Main MCP server setup.
• src/controllers/mcpController.ts: Tool registration and MCP controller handling incoming requests.
• src/services/: Service layer for handling Firestore interactions.
• src/tools/: Example tool definitions.
  • Each tool will have an inputSchema (Zod) and a handler.
  • Handlers will likely be wrapped with withWorkspaceAccess.
• src/utils/withWorkspaceAccess.ts: The Higher-Order Component for workspace checks.
• src/utils/fetchResourceList.ts: Example of reusable data fetching utility.
• src/utils/types.ts: Shared TypeScript types and Zod schemas (e.g., for EntityType, ResourceType).

Directory Structure

.
├── src/
│   ├── tools/                # Tool definitions
│   │   ├── getAgentTool.ts
│   │   └── ...
│   ├── utils/                # Shared utilities, HOCs, types
│   │   ├── withWorkspaceAccess.ts
│   │   ├── types.ts
│   │   └── ...
│   ├── services/             # Interaction logic
│   │   ├── firestoreService.ts    # Firestore interaction logic
│   │   └── ...
│   ├── config/               # Configuration loading
│   └── index.ts              # Main server setup
├── .env.example              # Example environment variables
├── .env                      # Your local environment variables (ignored by git)
├── package.json
├── tsconfig.json
└── ...

What This Demo Is (and Isn't)

• IS: A demonstration of server-side patterns for building a secure, multi-tenant MCP Resource Server.
• IS: A way to see TypeScript, Zod, Firestore, and OAuth concepts applied in an MCP context.
• IS NOT: A complete, production-ready OAuth Authorization Server (you need to provide that).
• IS NOT: A library or SDK to be directly consumed (it's an example application).
• IS NOT: Filled with complex business logic (tools are illustrative).

Contributing

This is primarily a demo repository. However, if you find bugs or have suggestions for improving the clarity of the demonstrated patterns, feel free to open an issue or submit a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

This demo is heavily inspired by the experiences and patterns discussed in the article: "Building a Production-Ready MCP Server with OAuth, TypeScript, and Our Battle Scars".