kym6464/mcp-server-remote

mcp-server-remote

This repository is a demonstration of a Remote MCP Server that uses Google as the identity provider, written in TypeScript. Watch this 2 minute video for an overview.

Getting Started

1. The first step is to acquire an OAuth Client ID and Client Secret by following this guide. The following Authorized redirect URIs are recommended:

   • http://localhost:6274/oauth/callback/debug - Used by the MCP Inspector authorization flow described in the testing section below
   • http://localhost:6274/oauth/callback - Used by the MCP Inspector
   • https://developers.google.com/oauthplayground - Used by Google's OAuth 2.0 Playground if you use your own credentials.

2. Once you have your Client ID and Client Secret, copy to .env.local and replace the fake values.

3. Run pnpm install followed by pnpm run dev. You should see the following output in your terminal:

   Authorization Server listening on port 3001
   MCP Streamable HTTP Server listening on port 3000
   

4. Follow the testing section below to test your MCP server.

(OPTIONAL) Claude Code setup

1. The requires that you have jq installed on your system.

2. expects that you have the https://github.com/modelcontextprotocol/typescript-sdk cloned to ../mcp-typescript-sdk. This makes it easier for Claude to reference the SDK source code without having to dig through node_modules.

3. Create .claude/settings.local.json based on the following:

   {
     "permissions": {
       "additionalDirectories": [
         "/path/to/mcp-typescript-sdk" // TODO
       ]
     },
     "hooks": {
       "PreToolUse": [
         {
           "matcher": "Read",
           "hooks": [
             {
               "type": "command",
               "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-env-files.sh"
             }
           ]
         }
       ]
     }
   }
   

Testing

1. Start the server via pnpm run dev
2. Start the MCP Inspector via npx @modelcontextprotocol/inspector and set the following options in the left pane:
   • Transport Type: Streamable HTTP
   • URL: http://localhost:3000/mcp
   • Connection Type: Direct
3. To test authentication, do not click the Connect button. Instead,
   • click Open Auth Settings button
   • in the OAuth Authentication card, click Guided Token Refresh
   • click through using the Continue button
4. To test the MCP server, click the Connect button.

Development

Code Structure

• - Starts the MCP and Authorization servers
• - Handles authentication via Google OAuth
• - Supports graceful shutdown
• - Defines the MCP tools, resources, etc.

Authorization Approach

Because Google doesn't support Dynamic Client Registration (DCR), we need to bridge the gap by presenting a DCR-compliant interface to MCP clients while using our pre-registered Google OAuth client credentials. This approach was inspired by FastMCP's OAuthProxy.

Graceful Shutdown

The acts as a central registry where other modules can register their cleanup methods. This is useful for modules that create stateful resources (e.g. database connections, HTTP servers) that need to be gracefully cleaned up before Node.js exits.

Without a central registry, we'd need to:

• Keep track of all stateful resources
• Remember to call cleanup on each one
• Handle errors from each cleanup separately
• Call process.exit which is not recommended

With this module, we only need to call a single disconnect() function and everything gets shut down gracefully.

History

This code was initialized from simpleStatelessStreamableHttp.ts example from the MCP TypeScript SDK.