mcp-workshop

English | 繁體中文 | 簡體中文

This workshop provides a comprehensive guide to building MCP (Model Context Protocol) servers and clients using the Go programming language. You will learn how to leverage MCP to streamline your workflow and enhance your development environment.

📖 Slides: Building MCP (Model Context Protocol) with Golang

Table of Contents

• mcp-workshop
  • Table of Contents
  • Workshop Modules
    • Modules Overview
  • VS Code MCP Configuration
    • Structure
      • Example (.vscode/mcp.json)
    • Usage
  • MCP Inspector Tool
  • OAuth Protocol in MCP
  • MCP Vulnerabilities
  • Reference Links

📖 Slides: Building MCP (Model Context Protocol) with Golang

Workshop Modules

This workshop consists of hands-on modules, each demonstrating a key aspect of building MCP (Model Context Protocol) servers and related infrastructure in Go.

Modules Overview

• 01. Basic MCP Server:
  • Minimal MCP server supporting both stdio and HTTP, using Gin. Shows server setup, tool registration, and logging/error handling best practices.
  • Key features: Dual transport (stdio/HTTP), Gin integration, extensible tool registration.
• 02. Basic Token Passthrough:
  • Transparent authentication token passthrough for HTTP and stdio. Demonstrates context injection and tool development for authenticated requests.
  • Key features: Token passthrough, context injection, example authenticated tools.
• 03. OAuth MCP Server:
  • MCP server with OAuth 2.0 protection. Example endpoints for auth, tokens, resource metadata; context-based token handling and authenticated API usage.
  • Key features: OAuth 2.0 flow, protected endpoints, context-based token propagation, demo tools.
• 04. Observability:
  • Observability and tracing for MCP servers using OpenTelemetry and structured logging. Includes metrics, detailed traces, and error reporting.
  • Key features: Tracing, structured logging, observability middleware, error reporting.
• 05. MCP Proxy:
  • Proxy server that aggregates multiple MCP servers behind one endpoint. Supports live streaming and centralizes configuration/security.
  • Key features: Unified access, SSE/HTTP streaming, flexible config, improved security.

Refer to each module’s directory and README.md for detailed instructions and code examples

VS Code MCP Configuration

The .vscode/mcp.json file configures MCP-related development in VS Code, allowing you to register servers and store required credentials (such as API keys) in a single place. This enables easy integration and switching between different MCP endpoints and credential sets.

Structure

• inputs: Prompt the user for required values (e.g., API keys) when the workspace is opened.
  • Example: perplexity-key – stores your Perplexity API Key as a password input.
• servers: Define named MCP server connections, including protocol, endpoint, and optional headers.
  • Examples:
    • default-stdio-server: Connects to a local MCP server using stdio via mcp-server.
    • default-http-server: Connects to a remote MCP server over HTTP, using an authorization header.
    • default-oauth-server, proxy-server-01, proxy-server-02: Additional HTTP(S) endpoints, with or without headers.

Example (.vscode/mcp.json)

{
  "inputs": [
    {
      "type": "promptString",
      "id": "perplexity-key",
      "description": "Perplexity API Key",
      "password": true
    }
  ],
  "servers": {
    "default-stdio-server": {
      "type": "stdio",
      "command": "mcp-server",
      "args": ["-t", "stdio"]
    },
    "default-http-server": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer 1234567890"
      }
    }
    // ... more server entries ...
  }
}

Usage

1. Place .vscode/mcp.json in the root or .vscode/ directory of your workspace.
2. Add/modify inputs for required user secrets.
3. Configure servers with endpoints for each service you want to register (specify type, command, URL, and headers as needed).
4. On opening the workspace, VS Code and supported MCP tools will prompt for the required inputs and use the server connections for MCP operations.

For further customization or advanced usage, edit the file to add endpoints or credentials. Centralized configuration streamlines connection management and development.

MCP Inspector Tool

The MCP Inspector is a developer tool (similar to Postman) for testing and debugging MCP servers. Use it to send requests and view responses from MCP endpoints—ideal for streamlining development and troubleshooting.

OAuth Protocol in MCP

The following diagrams illustrate the OAuth flow within MCP, detailing the sequence of communication between roles.

Sequence diagram showing communication with each role separately:

For more information:

• Let's fix OAuth in MCP
• MCP Authorization

The full OAuth access token flow is depicted in the MCP Specification. A simplified sequence:

sequenceDiagram
    participant B as User-Agent (Browser)
    participant C as Client
    participant M as MCP Server (Resource Server)
    participant A as Authorization Server

    C->>M: MCP request without token
    M->>C: HTTP 401 Unauthorized with WWW-Authenticate header
    Note over C: Extract resource_metadata URL from WWW-Authenticate

    C->>M: Request Protected Resource Metadata
    M->>C: Return metadata

    Note over C: Parse metadata and extract authorization server(s)<br/>Client determines AS to use

    C->>A: GET /.well-known/oauth-authorization-server
    A->>C: Authorization server metadata response

    alt Dynamic client registration
        C->>A: POST /register
        A->>C: Client Credentials
    end

    Note over C: Generate PKCE parameters
    C->>B: Open browser with authorization URL + code_challenge
    B->>A: Authorization request
    Note over A: User authorizes
    A->>B: Redirect to callback with authorization code
    B->>C: Authorization code callback
    C->>A: Token request + code_verifier
    A->>C: Access token (+ refresh token)
    C->>M: MCP request with access token
    M-->>C: MCP response
    Note over C,M: MCP communication continues with valid token

Note: Dynamic Client Registration is NOT supported by Remote MCP Server at this time.

MCP Vulnerabilities

Some known vulnerabilities in MCP implementations:

• Command Injection (Impact: Moderate 🟡)
• Tool Poisoning (Impact: Severe 🔴)
• Open Connections via SSE (Impact: Moderate 🟠)
• Privilege Escalation (Impact: Severe 🔴)
• Persistent Context Misuse (Impact: Low, but risky 🟡)
• Server Data Takeover/Spoofing (Impact: Severe 🔴)

For more information, see MCP Vulnerabilities.

Reference Links

• An Introduction to MCP and Authorization
• Auth0 for MCP Servers
• Understanding OAuth2 and implementing identity-aware MCP servers
• Enterprise-Ready MCP
• [Session] Intro to OAuth for MCP Servers with Aaron Parecki, Okta
• OAuth 2 PKCE Complete Explanation (Chinese)
• OAuth 2.0 Study Notes - PKCE (Chinese)
• OAuth 2.0 Notes (2) Client Registration and Authentication (Chinese)
• OAuth 2.0 Authorization Code Flow Configuration Guide (Chinese)