mcp-server-lib

A factory for creating Google OAuth-authenticated MCP (Model Context Protocol) servers in Node.js. Handles the full OAuth 2.0 PKCE flow, bearer token validation, and per-user scoped tool execution — so you only need to define your tools.

Installation

npm install mcp-server-lib

Quick Start

import { createMcpServer } from "mcp-server-lib";
import { z } from "zod";

createMcpServer({
  name: "my-server",
  port: 3001,
  googleClientId: process.env.GOOGLE_CLIENT_ID!,
  googleClientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  mcpApiKey: process.env.MCP_API_KEY!,
  tools: [
    {
      name: "list_items",
      description: "Get all items for the authenticated user",
      handler: async (_args, { userEmail }) => {
        // userEmail is the Google-authenticated user's email
        return { items: [], user: userEmail };
      },
    },
    {
      name: "create_item",
      description: "Create a new item",
      inputSchema: {
        title: z.string(),
        priority: z.enum(["low", "medium", "high"]).optional(),
      },
      handler: async ({ title, priority }, { userEmail }) => {
        // your logic here
        return { created: true, title, priority, by: userEmail };
      },
    },
  ],
});

Google OAuth Setup

1. Go to the Google Cloud Console and create an OAuth 2.0 client ID (type: Web application).
2. Add your callback URL to Authorized redirect URIs:
   • Local: http://localhost:3001/callback
   • Production: https://your-domain.com/callback
3. Copy the Client ID and Client Secret into your environment variables.

Configuration

| Option | Type | Required | Default | Description | | -------------------- | ------------ | -------- | --------------------------- | ------------------------------------------------------------------------ | | name | string | Yes | — | Display name reported to MCP clients during initialization. | | googleClientId | string | Yes | — | Google OAuth 2.0 client ID. | | googleClientSecret | string | Yes | — | Google OAuth 2.0 client secret. | | mcpApiKey | string | Yes | — | Shared secret; MCP clients must send this as a Bearer token. | | tools | McpTool[] | Yes | — | Array of tools to expose on the MCP server. | | port | number | No | 3001 | TCP port to listen on. | | baseUrl | string | No | http://localhost:<port> | Publicly reachable base URL. Set this in production. | | version | string | No | "1.0.0" | Server version string reported to clients. |

Defining Tools

Each tool in the tools array follows the McpTool interface:

interface McpTool {
  name: string;                                       // unique tool identifier
  description: string;                                // shown to MCP clients / AI agents
  inputSchema?: Record<string, z.ZodTypeAny>;         // optional argument validation
  handler: (args: any, context: { userEmail: string }) => Promise<any>;
}

• inputSchema uses Zod validators. When provided, the MCP SDK describes the expected arguments to clients automatically.
• handler receives validated args and a context object with the authenticated userEmail. Return any JSON-serializable value.

HTTP Routes

| Method | Path | Description | | ------ | ----------- | ---------------------------------------------------- | | GET | /callback | Google OAuth redirect handler (do not call directly) | | * | /mcp | MCP protocol endpoint — requires valid bearer token |

The MCP SDK auth router also mounts standard OAuth discovery/token endpoints automatically.

Environment Variables

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
MCP_API_KEY=your-secret-api-key

Logging

All library logs are prefixed with [mcp-server-lib] so you can easily identify them. Key events logged:

• Server started
• OAuth client registered
• Authorization flow started / user authenticated
• Access token issued / revoked / expired
• MCP request received
• Tool called

Limitations

• In-memory state: All OAuth clients, sessions, and access tokens are stored in process memory. They are lost on server restart. For production deployments with multiple instances, you would need to replace the in-memory maps with a shared store (e.g. Redis).
• No refresh tokens: Access tokens are valid for 8 hours. After expiry, users must re-authenticate via Google.
• Single identity provider: Only Google OAuth is supported as the identity provider.

License

ISC