Integrating your own MCP client

npm install @modelcontextprotocol/sdk
npm install oauth  # or openid-client

npm install --save-dev @types/node

type OAuthMetadata = {
  issuer: string
  authorization_endpoint: string
  token_endpoint: string
  registration_endpoint?: string
  code_challenge_methods_supported?: string[]
  grant_types_supported?: string[]
  response_types_supported?: string[]
  scopes_supported?: string[]
}

/**
 * Discovers OAuth configuration for an MCP server using RFC 9470 + RFC 8414.
 */
async function discoverOAuthMetadata(
  mcpServerUrl: string
): Promise<OAuthMetadata> {
  const url = new URL(mcpServerUrl)
  const protectedResourceUrl = new URL(
    "/.well-known/oauth-protected-resource",
    url
  )

  // Step 1: RFC 9470 - Get Protected Resource Metadata
  const protectedResourceResponse = await fetch(
    protectedResourceUrl.toString()
  )
  if (!protectedResourceResponse.ok) {
    throw new Error(
      `Failed to fetch protected resource metadata: ` +
      `${protectedResourceResponse.status}`
    )
  }

  const protectedResource = await protectedResourceResponse.json()
  const authServers = protectedResource.authorization_servers

  if (!Array.isArray(authServers) || authServers.length === 0) {
    throw new Error(
      "No authorization servers found in protected resource metadata"
    )
  }

  // Use the first authorization server
  const authServerUrl = authServers[0]

  // Step 2: RFC 8414 - Get Authorization Server Metadata
  const metadataUrl = new URL(
    "/.well-known/oauth-authorization-server",
    authServerUrl
  )
  const metadataResponse = await fetch(metadataUrl.toString())

  if (!metadataResponse.ok) {
    throw new Error(
      `Failed to fetch authorization server metadata: ` +
      `${metadataResponse.status}`
    )
  }

  const metadata = (await metadataResponse.json()) as OAuthMetadata

  // Validate required fields
  if (!metadata.authorization_endpoint || !metadata.token_endpoint) {
    throw new Error("Missing required OAuth endpoints in metadata")
  }

  // Warn if PKCE support isn't advertised
  if (!metadata.code_challenge_methods_supported?.includes("S256")) {
    console.warn(
      "Server does not advertise S256 PKCE support, " +
      "but we will use it anyway"
    )
  }

  return metadata
}

import { randomBytes, createHash } from "crypto"

function base64URLEncode(str: Buffer): string {
  return str
    .toString("base64")
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=/g, "")
}

function generateCodeVerifier(): string {
  // Generate 32 random bytes = 256 bits
  // Base64 encoding produces ~43 characters
  const bytes = randomBytes(32)
  return base64URLEncode(bytes)
}

function generateCodeChallenge(verifier: string): string {
  const hash = createHash("sha256").update(verifier).digest()
  return base64URLEncode(hash)
}

// Usage
const codeVerifier = generateCodeVerifier()
const codeChallenge = generateCodeChallenge(codeVerifier)

// Store codeVerifier securely - you'll need it for token exchange

type ClientRegistration = {
  client_name: string
  client_uri?: string
  redirect_uris: string[]
  grant_types: string[]
  response_types: string[]
  token_endpoint_auth_method: string
  scope?: string
}

type ClientCredentials = {
  client_id: string
  client_secret?: string
  client_id_issued_at?: number
  client_secret_expires_at?: number
}

async function registerClient(
  metadata: OAuthMetadata,
  redirectUri: string
): Promise<ClientCredentials> {
  if (!metadata.registration_endpoint) {
    throw new Error("Server does not support dynamic client registration")
  }

  const registrationRequest: ClientRegistration = {
    client_name: "Your MCP Client",
    client_uri: "https://example.com",
    redirect_uris: [redirectUri],
    grant_types: ["authorization_code", "refresh_token"],
    response_types: ["code"],
    token_endpoint_auth_method: "none",
  }

  const response = await fetch(metadata.registration_endpoint, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify(registrationRequest),
  })

  if (!response.ok) {
    const errorBody = await response.text()
    throw new Error(
      `Client registration failed: ${response.status} - ${errorBody}`
    )
  }

  const credentials = (await response.json()) as ClientCredentials

  // Store credentials securely
  return credentials
}

function buildAuthorizationUrl(
  metadata: OAuthMetadata,
  clientId: string,
  redirectUri: string,
  codeChallenge: string,
  state: string,
  scopes: string[] = []
): string {
  const params = new URLSearchParams({
    response_type: "code",
    client_id: clientId,
    redirect_uri: redirectUri,
    scope: scopes.join(" "),
    state: state,
    code_challenge: codeChallenge,
    code_challenge_method: "S256",
    prompt: "consent",
  })

  return `${metadata.authorization_endpoint}?${params.toString()}`
}

function generateState(): string {
  return randomBytes(32).toString("hex")
}

// Usage
const state = generateState()
const authorizationUrl = buildAuthorizationUrl(
  metadata,
  clientId,
  redirectUri,
  codeChallenge,
  state
)

// Store state and codeVerifier in secure session storage
// Redirect user to authorizationUrl
window.location.href = authorizationUrl // Browser redirect

interface CallbackParams {
  code?: string
  state?: string
  error?: string
  error_description?: string
}

function parseCallback(url: string): CallbackParams {
  const urlParams = new URLSearchParams(new URL(url).search)

  return {
    code: urlParams.get("code") || undefined,
    state: urlParams.get("state") || undefined,
    error: urlParams.get("error") || undefined,
    error_description: urlParams.get("error_description") || undefined,
  }
}

async function handleCallback(
  callbackUrl: string,
  storedState: string,
  codeVerifier: string
): Promise<string> {
  const params = parseCallback(callbackUrl)

  if (params.error) {
    throw new Error(
      `OAuth error: ${params.error} - ` +
      `${params.error_description || "Unknown error"}`
    )
  }

  if (params.state !== storedState) {
    throw new Error("Invalid state parameter - possible CSRF attack")
  }

  if (!params.code) {
    throw new Error("Missing authorization code")
  }

  return params.code
}

type TokenResponse = {
  access_token: string
  token_type: string
  expires_in?: number
  refresh_token?: string
  scope?: string
  // Identity fields, present on successful authorization-code exchanges
  user_id?: string
  workspace_id?: string
  email_domain?: string
}

async function exchangeCodeForTokens(
  code: string,
  codeVerifier: string,
  metadata: OAuthMetadata,
  clientId: string,
  clientSecret: string | undefined,
  redirectUri: string
): Promise<TokenResponse> {
  const params = new URLSearchParams({
    grant_type: "authorization_code",
    code: code,
    client_id: clientId,
    redirect_uri: redirectUri,
    code_verifier: codeVerifier,
  })

  if (clientSecret) {
    params.append("client_secret", clientSecret)
  }

  const response = await fetch(metadata.token_endpoint, {
    method: "POST",
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      Accept: "application/json",
      "User-Agent": "YourApp-MCP-Client/1.0",
    },
    body: params.toString(),
  })

  if (!response.ok) {
    const errorBody = await response.text()
    throw new Error(
      `Token exchange failed: ${response.status} - ${errorBody}`
    )
  }

  const tokens = await response.json()

  if (!tokens.access_token) {
    throw new Error("Missing access_token in response")
  }

  return tokens
}

import { Client } from "@modelcontextprotocol/sdk/client/index.js"
import {
  StreamableHTTPClientTransport
} from "@modelcontextprotocol/sdk/client/streamableHttp.js"
import {
  SSEClientTransport
} from "@modelcontextprotocol/sdk/client/sse.js"

async function createMcpClient(
  serverUrl: string,
  accessToken: string,
  useSSE: boolean = false
): Promise<Client> {
  const client = new Client(
    {
      name: "your-mcp-client",
      version: "1.0.0",
    },
    {
      capabilities: {
        roots: {},
        sampling: {},
      },
    }
  )

  let transport

  if (useSSE) {
    transport = new SSEClientTransport(new URL(`${serverUrl}/sse`), {
      requestInit: {
        headers: {
          Authorization: `Bearer ${accessToken}`,
          "User-Agent": "YourApp-MCP-Client/1.0",
        },
      },
    })
  } else {
    transport = new StreamableHTTPClientTransport(
      new URL(`${serverUrl}/mcp`),
      {
        requestInit: {
          headers: {
            Authorization: `Bearer ${accessToken}`,
            "User-Agent": "YourApp-MCP-Client/1.0",
          },
        },
      }
    )
  }

  await client.connect(transport)

  return client
}

// Usage with automatic fallback
async function connectToNotionMcp(accessToken: string): Promise<Client> {
  const serverUrl = "https://mcp.notion.com"

  try {
    return await createMcpClient(serverUrl, accessToken, false)
  } catch (error) {
    console.warn("Streamable HTTP failed, falling back to SSE:", error)
    return await createMcpClient(serverUrl, accessToken, true)
  }
}

const result = await client.callTool({
  name: "notion-fetch", // "fetch" for OpenAI clients (the notion- prefix is dropped)
  arguments: { id: "self" },
})

// Tool results come back as MCP content blocks, not as a typed object. The Notion
// MCP server returns the tool's JSON payload as a single text block, so parse it
// and read the `self` field from the result.
const [block] = result.content
if (block?.type !== "text") {
  throw new Error("Expected a text content block from notion-fetch")
}

const { workspace, user } = JSON.parse(block.text).self
console.log(`Connected to ${workspace.name} (${workspace.id}) as ${user.name}`)
// workspace: { id, name }
// user:      { id, name, type, email }