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".