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

Clone the repository:

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

Install dependencies:
```
npm install
# or
yarn install
```

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.

(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

Ensure Google Cloud SDK is installed and configured.
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).
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".

MCP Servers