MCP 2025-03-26 Spec Breakdown: OAuth Authentication, Remote Connections & Tool Annotations

POST /register HTTP/1.1
Content-Type: application/json

{
  "client_name": "My AI Assistant",
  "redirect_uris": ["http://localhost:3000/callback"],
  "grant_types": ["authorization_code"],
  "token_endpoint_auth_method": "none"
}

import express from 'express';
import crypto from 'crypto';
import jwt from 'jsonwebtoken';

const app = express();
app.use(express.json());

// --- OAuth 2.1 Endpoints ---

// Authorization server metadata discovery
app.get('/.well-known/oauth-authorization-server', (req, res) => {
  res.json({
    issuer: 'https://mcp.example.com',
    authorization_endpoint: 'https://mcp.example.com/authorize',
    token_endpoint: 'https://mcp.example.com/token',
    registration_endpoint: 'https://mcp.example.com/register',
    response_types_supported: ['code'],
    code_challenge_methods_supported: ['S256'],
    grant_types_supported: ['authorization_code', 'refresh_token']
  });
});

// Dynamic Client Registration (RFC 7591)
const clients = new Map();
app.post('/register', (req, res) => {
  const clientId = crypto.randomUUID();
  clients.set(clientId, {
    client_name: req.body.client_name,
    redirect_uris: req.body.redirect_uris,
    created_at: Date.now()
  });
  res.status(201).json({ client_id: clientId });
});

// Token endpoint (PKCE verification)
app.post('/token', (req, res) => {
  const { code, code_verifier, client_id } = req.body;
  const stored = authCodes.get(code);
  if (!stored) return res.status(400).json({ error: 'invalid_grant' });

  // Verify PKCE: SHA256(code_verifier) === code_challenge
  const challenge = crypto
    .createHash('sha256')
    .update(code_verifier)
    .digest('base64url');
  if (challenge !== stored.code_challenge) {
    return res.status(400).json({ error: 'invalid_grant' });
  }

  const accessToken = jwt.sign(
    { sub: stored.user_id, client_id, scope: stored.scope },
    process.env.JWT_SECRET,
    { expiresIn: '15m' }
  );
  const refreshToken = crypto.randomUUID();

  res.json({
    access_token: accessToken,
    token_type: 'Bearer',
    expires_in: 900,
    refresh_token: refreshToken
  });
});

// --- MCP Streamable HTTP Endpoint ---
app.post('/mcp', authenticateToken, (req, res) => {
  const body = req.body;
  if (Array.isArray(body)) {
    // Batch mode
    const results = body.map(msg => handleJsonRpc(msg, req.user));
    res.json(results.filter(r => r !== null));
  } else {
    const result = handleJsonRpc(body, req.user);
    result ? res.json(result) : res.status(202).end();
  }
});

function authenticateToken(req, res, next) {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) return res.status(401).json({ error: 'unauthorized' });
  try {
    req.user = jwt.verify(token, process.env.JWT_SECRET);
    next();
  } catch {
    res.status(403).json({ error: 'invalid_token' });
  }
}

import hashlib
import base64
import os
import httpx

class MCPOAuthClient:
    def __init__(self, server_url: str):
        self.server_url = server_url
        self.client_id = None
        self.access_token = None

    async def discover(self):
        """Discover authorization server metadata"""
        async with httpx.AsyncClient() as client:
            resp = await client.get(
                f"{self.server_url}/.well-known/oauth-authorization-server"
            )
            return resp.json()

    async def register(self):
        """Dynamic client registration"""
        async with httpx.AsyncClient() as client:
            resp = await client.post(
                f"{self.server_url}/register",
                json={
                    "client_name": "Python MCP Client",
                    "redirect_uris": ["http://localhost:8080/callback"],
                    "grant_types": ["authorization_code"]
                }
            )
            self.client_id = resp.json()["client_id"]

    def generate_pkce(self) -> tuple[str, str]:
        """Generate PKCE code_verifier and code_challenge"""
        code_verifier = base64.urlsafe_b64encode(
            os.urandom(32)
        ).decode('utf-8').rstrip('=')
        code_challenge = base64.urlsafe_b64encode(
            hashlib.sha256(code_verifier.encode()).digest()
        ).decode('utf-8').rstrip('=')
        return code_verifier, code_challenge

    async def exchange_token(self, code: str, code_verifier: str):
        """Exchange authorization code + code_verifier for Access Token"""
        async with httpx.AsyncClient() as client:
            resp = await client.post(
                f"{self.server_url}/token",
                data={
                    "grant_type": "authorization_code",
                    "code": code,
                    "code_verifier": code_verifier,
                    "client_id": self.client_id
                }
            )
            tokens = resp.json()
            self.access_token = tokens["access_token"]
            return tokens

    async def call_tool(self, tool_name: str, arguments: dict):
        """Call an MCP tool"""
        async with httpx.AsyncClient() as client:
            resp = await client.post(
                f"{self.server_url}/mcp",
                headers={"Authorization": f"Bearer {self.access_token}"},
                json={
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "tools/call",
                    "params": {
                        "name": tool_name,
                        "arguments": arguments
                    }
                }
            )
            return resp.json()

POST /mcp HTTP/1.1
Content-Type: application/json
Accept: application/json, text/event-stream
Mcp-Session-Id: sess_abc123

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "long_running_task", "arguments": {} }
}

HTTP/1.1 200 OK
Content-Type: application/json

{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "done"}]}}

HTTP/1.1 200 OK
Content-Type: text/event-stream

event: message
data: {"jsonrpc":"2.0","method":"notifications/progress","params":{"progress":50,"message":"Processing..."}}

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"Complete"}]}}

// Client reconnection logic
async function reconnect(sessionId, lastEventId) {
  const response = await fetch('/mcp', {
    method: 'GET',
    headers: {
      'Accept': 'text/event-stream',
      'Mcp-Session-Id': sessionId,
      'Last-Event-ID': lastEventId
    }
  });
  // Server continues pushing events from after lastEventId
  const reader = response.body.getReader();
  // ... process SSE event stream
}

interface ToolAnnotations {
  title?: string;              // Semantic title (for UI display)
  readOnlyHint?: boolean;      // Read-only (default: false)
  destructiveHint?: boolean;   // Destructive (default: true)
  idempotentHint?: boolean;    // Idempotent (default: false)
  openWorldHint?: boolean;     // External interaction (default: true)
}

{
  "tools": [
    {
      "name": "query_database",
      "description": "Execute a read-only SQL query",
      "inputSchema": {
        "type": "object",
        "properties": {
          "sql": { "type": "string" }
        }
      },
      "annotations": {
        "title": "Database Query",
        "readOnlyHint": true,
        "destructiveHint": false,
        "idempotentHint": true,
        "openWorldHint": false
      }
    },
    {
      "name": "delete_user",
      "description": "Permanently delete a user account",
      "inputSchema": {
        "type": "object",
        "properties": {
          "user_id": { "type": "string" }
        }
      },
      "annotations": {
        "title": "Delete User Account",
        "readOnlyHint": false,
        "destructiveHint": true,
        "idempotentHint": false,
        "openWorldHint": false
      }
    },
    {
      "name": "send_email",
      "description": "Send an email to the specified recipient",
      "inputSchema": {
        "type": "object",
        "properties": {
          "to": { "type": "string" },
          "subject": { "type": "string" },
          "body": { "type": "string" }
        }
      },
      "annotations": {
        "title": "Send Email",
        "readOnlyHint": false,
        "destructiveHint": false,
        "idempotentHint": false,
        "openWorldHint": true
      }
    }
  ]
}

[
  {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "analyze_text", "arguments": {"text": "hello"}}},
  {"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "translate", "arguments": {"text": "hello", "target": "zh"}}},
  {"jsonrpc": "2.0", "method": "notifications/initialized"}
]

{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "task_123",
    "progress": 65,
    "total": 100,
    "message": "Data cleaning: processed 12000/20000 records"
  }
}

// ❌ Legacy: Dual-endpoint HTTP+SSE
app.get('/sse', handleSSE);
app.post('/message', handleMessage);

// ✅ New: Single-endpoint Streamable HTTP
app.post('/mcp', handleStreamableHTTP);
app.get('/mcp', handleSSEStream); // Optional: for server-initiated push

// Add metadata discovery endpoint
app.get('/.well-known/oauth-authorization-server', (req, res) => {
  res.json({ /* auth server configuration */ });
});

// Add dynamic client registration
app.post('/register', handleDynamicRegistration);

// Add auth middleware to all MCP endpoints
app.post('/mcp', authenticateOAuth, handleMCP);

// ❌ Legacy: Basic description only
{ name: 'delete_file', description: 'Delete a file' }

// ✅ New: Includes behavioral metadata
{
  name: 'delete_file',
  description: 'Delete a file',
  annotations: {
    title: 'Delete File',
    readOnlyHint: false,
    destructiveHint: true,
    idempotentHint: false,
    openWorldHint: false
  }
}

app.post('/mcp', (req, res) => {
  // Handle Mcp-Session-Id
  const sessionId = req.headers['mcp-session-id'] || generateSessionId();
  res.setHeader('Mcp-Session-Id', sessionId);

  // Support batching
  if (Array.isArray(req.body)) {
    const results = req.body.map(msg => processMessage(msg, sessionId));
    return res.json(results.filter(Boolean));
  }
  // Single message handling
  const result = processMessage(req.body, sessionId);
  result ? res.json(result) : res.status(202).end();
});