🦑 dmcp 🦑

A TypeScript/JavaScript library for connecting to Model Context Protocol (MCP) servers. Provides OAuth authentication components and a React hook for easy integration with AI systems implementing the MCP standard.

Try it out: MCP Inspector | Cloudflare Workers AI Playground

Installation

npm install dmcp
# or
pnpm add dmcp
# or
yarn add dmcp

What's Included

• 🔐 OAuth Authentication Components - Framework-agnostic browser OAuth flow handling
• ⚛️ React Hook - Complete MCP client with connection management, tool calling, and state management
• 🧰 TypeScript Types - Full type safety and editor support

Framework Support

| Framework | OAuth Components | MCP Client | Status | |-----------|:----------------:|:----------:|:------:| | React | ✅ | ✅ | Full Support | | Vue.js | ✅ | ❌ | OAuth Only | | Angular | ✅ | ❌ | OAuth Only | | Svelte | ✅ | ❌ | OAuth Only | | Vanilla JS | ✅ | ❌ | OAuth Only |

Note: Currently, only React has a complete MCP client implementation. Other frameworks can use the OAuth components to handle authentication, but you'll need to implement the MCP client logic using the @modelcontextprotocol/sdk directly.

Quick Start

React (Complete MCP Client)

import { useMcp } from 'dmcp/react'

function MyAIComponent() {
  const {
    state,          // Connection state
    tools,          // Available tools from MCP server
    error,          // Error message if connection failed
    callTool,       // Function to call tools
    retry,          // Retry connection
    authenticate,   // Manual authentication trigger
    clearStorage,   // Clear stored credentials
  } = useMcp({
    url: 'https://your-mcp-server.com',
    clientName: 'My App',
    autoReconnect: true,
  })

  // Handle different connection states
  if (state === 'failed') {
    return (
      <div>
        <p>Connection failed: {error}</p>
        <button onClick={retry}>Retry</button>
        <button onClick={authenticate}>Authenticate Manually</button>
      </div>
    )
  }

  if (state !== 'ready') {
    return <div>Connecting to AI service...</div>
  }

  // Use available tools
  const handleSearch = async () => {
    try {
      const result = await callTool('search', { query: 'example search' })
      console.log('Search results:', result)
    } catch (err) {
      console.error('Tool call failed:', err)
    }
  }

  return (
    <div>
      <h2>Available Tools: {tools.length}</h2>
      <ul>
        {tools.map(tool => (
          <li key={tool.name}>{tool.name}</li>
        ))}
      </ul>
      <button onClick={handleSearch}>Search</button>
    </div>
  )
}

Other Frameworks (OAuth Only)

For Vue.js, Angular, Svelte, and vanilla JavaScript, dmcp provides OAuth authentication components. You'll need to implement the MCP client functionality yourself using the @modelcontextprotocol/sdk.

Basic OAuth Setup

import { BrowserOAuthClientProvider, onMcpAuthorization } from 'dmcp'
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js'

// Initialize OAuth provider
const authProvider = new BrowserOAuthClientProvider('https://your-mcp-server.com', {
  clientName: 'My App',
  storageKeyPrefix: 'myapp:auth'
})

// Create MCP client
const client = new Client(
  { name: 'my-app', version: '1.0.0' },
  { capabilities: {} }
)

// Create transport with auth
const transport = new SSEClientTransport(
  new URL('https://your-mcp-server.com'),
  { authProvider }
)

// Connect and use
try {
  await client.connect(transport)
  const tools = await client.request({ method: 'tools/list' })
  console.log('Available tools:', tools)
} catch (error) {
  console.error('Connection failed:', error)
}

OAuth Callback Setup

All frameworks need to set up an OAuth callback route to handle authentication redirects.

React Router

import { BrowserRouter as Router, Routes, Route } from 'react-router-dom'
import { useEffect } from 'react'
import { onMcpAuthorization } from 'dmcp'

function OAuthCallback() {
  useEffect(() => {
    onMcpAuthorization()
  }, [])

  return (
    <div>
      <h1>Authenticating...</h1>
      <p>This window should close automatically.</p>
    </div>
  )
}

function App() {
  return (
    <Router>
      <Routes>
        <Route path="/oauth/callback" element={<OAuthCallback />} />
        <Route path="/" element={<YourMainComponent />} />
      </Routes>
    </Router>
  )
}

Next.js Pages Router

// pages/oauth/callback.tsx
import { useEffect } from 'react'
import { onMcpAuthorization } from 'dmcp'

export default function OAuthCallbackPage() {
  useEffect(() => {
    onMcpAuthorization()
  }, [])

  return (
    <div>
      <h1>Authenticating...</h1>
      <p>This window should close automatically.</p>
    </div>
  )
}

Next.js App Router

// app/oauth/callback/page.tsx
'use client'
import { useEffect } from 'react'
import { onMcpAuthorization } from 'dmcp'

export default function OAuthCallbackPage() {
  useEffect(() => {
    onMcpAuthorization()
  }, [])

  return (
    <div>
      <h1>Authenticating...</h1>
      <p>This window should close automatically.</p>
    </div>
  )
}

Vue.js

<!-- OAuthCallback.vue -->
<template>
  <div>
    <h1>Authenticating...</h1>
    <p>This window should close automatically.</p>
  </div>
</template>

<script setup>
import { onMounted } from 'vue'
import { onMcpAuthorization } from 'dmcp'

onMounted(() => {
  onMcpAuthorization()
})
</script>

// router.js
import { createRouter, createWebHistory } from 'vue-router'
import OAuthCallback from './components/OAuthCallback.vue'
import Home from './components/Home.vue'

const routes = [
  { path: '/', component: Home },
  { path: '/oauth/callback', component: OAuthCallback }
]

export default createRouter({
  history: createWebHistory(),
  routes
})

Angular

// oauth-callback.component.ts
import { Component, OnInit } from '@angular/core'
import { onMcpAuthorization } from 'dmcp'

@Component({
  selector: 'app-oauth-callback',
  template: `
    <div>
      <h1>Authenticating...</h1>
      <p>This window should close automatically.</p>
    </div>
  `
})
export class OAuthCallbackComponent implements OnInit {
  ngOnInit() {
    onMcpAuthorization()
  }
}

// app-routing.module.ts
import { NgModule } from '@angular/core'
import { RouterModule, Routes } from '@angular/router'
import { OAuthCallbackComponent } from './oauth-callback.component'

const routes: Routes = [
  { path: 'oauth/callback', component: OAuthCallbackComponent },
  // other routes...
]

@NgModule({
  imports: [RouterModule.forRoot(routes)],
  exports: [RouterModule]
})
export class AppRoutingModule { }

Svelte/SvelteKit

<!-- src/routes/oauth/callback/+page.svelte -->
<script>
  import { onMount } from 'svelte'
  import { onMcpAuthorization } from 'dmcp'

  onMount(() => {
    onMcpAuthorization()
  })
</script>

<div>
  <h1>Authenticating...</h1>
  <p>This window should close automatically.</p>
</div>

Vanilla JavaScript

<!-- /oauth/callback.html -->
<!DOCTYPE html>
<html>
<head>
  <title>OAuth Callback</title>
</head>
<body>
  <h1>Authenticating...</h1>
  <p>This window should close automatically.</p>
  
  <script type="module">
    import { onMcpAuthorization } from 'dmcp'
    onMcpAuthorization()
  </script>
</body>
</html>

Framework-Specific Examples

Vue.js MCP Integration

<template>
  <div>
    <div v-if="connecting">Connecting to MCP server...</div>
    <div v-else-if="error" class="error">
      Error: {{ error }}
      <button @click="reconnect">Retry</button>
    </div>
    <div v-else>
      <h2>Available Tools: {{ tools.length }}</h2>
      <button @click="callExampleTool">Call Tool</button>
    </div>
  </div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
import { BrowserOAuthClientProvider } from 'dmcp'
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js'

const tools = ref([])
const error = ref(null)
const connecting = ref(true)

let client = null
let transport = null

const initMcp = async () => {
  try {
    const authProvider = new BrowserOAuthClientProvider('https://your-mcp-server.com', {
      clientName: 'Vue MCP App'
    })

    client = new Client(
      { name: 'vue-mcp-client', version: '1.0.0' },
      { capabilities: {} }
    )

    transport = new SSEClientTransport(
      new URL('https://your-mcp-server.com'),
      { authProvider }
    )

    await client.connect(transport)
    const toolsResponse = await client.request({ method: 'tools/list' })
    tools.value = toolsResponse.tools
    error.value = null
  } catch (err) {
    error.value = err.message
  } finally {
    connecting.value = false
  }
}

const callExampleTool = async () => {
  if (!client || tools.value.length === 0) return
  
  try {
    const result = await client.request({
      method: 'tools/call',
      params: {
        name: tools.value[0].name,
        arguments: {}
      }
    })
    console.log('Tool result:', result)
  } catch (err) {
    console.error('Tool call failed:', err)
  }
}

const reconnect = () => {
  connecting.value = true
  error.value = null
  initMcp()
}

onMounted(initMcp)

onUnmounted(() => {
  if (transport) {
    transport.close()
  }
})
</script>

<style>
.error {
  color: red;
  padding: 10px;
  border: 1px solid red;
  border-radius: 4px;
  margin: 10px 0;
}
</style>

Angular MCP Service

// mcp.service.ts
import { Injectable } from '@angular/core'
import { BehaviorSubject, Observable } from 'rxjs'
import { BrowserOAuthClientProvider } from 'dmcp'
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js'

export interface McpState {
  connected: boolean
  tools: any[]
  error: string | null
  loading: boolean
}

@Injectable({
  providedIn: 'root'
})
export class McpService {
  private client: Client | null = null
  private transport: any = null
  
  private stateSubject = new BehaviorSubject<McpState>({
    connected: false,
    tools: [],
    error: null,
    loading: false
  })

  public state$: Observable<McpState> = this.stateSubject.asObservable()

  async connect(serverUrl: string, clientName: string = 'Angular MCP App') {
    this.updateState({ loading: true, error: null })

    try {
      const authProvider = new BrowserOAuthClientProvider(serverUrl, {
        clientName
      })

      this.client = new Client(
        { name: 'angular-mcp-client', version: '1.0.0' },
        { capabilities: {} }
      )

      this.transport = new SSEClientTransport(
        new URL(serverUrl),
        { authProvider }
      )

      await this.client.connect(this.transport)
      const toolsResponse = await this.client.request({ method: 'tools/list' })
      
      this.updateState({
        connected: true,
        tools: toolsResponse.tools,
        loading: false,
        error: null
      })
    } catch (error) {
      this.updateState({
        connected: false,
        loading: false,
        error: error instanceof Error ? error.message : 'Connection failed'
      })
    }
  }

  async callTool(name: string, args: any = {}) {
    if (!this.client) {
      throw new Error('Not connected to MCP server')
    }

    return await this.client.request({
      method: 'tools/call',
      params: { name, arguments: args }
    })
  }

  disconnect() {
    if (this.transport) {
      this.transport.close()
    }
    this.updateState({
      connected: false,
      tools: [],
      error: null,
      loading: false
    })
  }

  private updateState(partialState: Partial<McpState>) {
    const currentState = this.stateSubject.value
    this.stateSubject.next({ ...currentState, ...partialState })
  }
}

// mcp.component.ts
import { Component, OnInit, OnDestroy } from '@angular/core'
import { McpService, McpState } from './mcp.service'
import { Observable } from 'rxjs'

@Component({
  selector: 'app-mcp',
  template: `
    <div *ngIf="state$ | async as state">
      <div *ngIf="state.loading">Connecting to MCP server...</div>
      
      <div *ngIf="state.error" class="error">
        Error: {{ state.error }}
        <button (click)="connect()">Retry</button>
      </div>
      
      <div *ngIf="state.connected">
        <h2>Available Tools: {{ state.tools.length }}</h2>
        <ul>
          <li *ngFor="let tool of state.tools">
            {{ tool.name }}
            <button (click)="callTool(tool.name)">Call</button>
          </li>
        </ul>
        <button (click)="disconnect()">Disconnect</button>
      </div>
    </div>
  `,
  styles: [`
    .error {
      color: red;
      padding: 10px;
      border: 1px solid red;
      border-radius: 4px;
      margin: 10px 0;
    }
  `]
})
export class McpComponent implements OnInit, OnDestroy {
  state$: Observable<McpState>

  constructor(private mcpService: McpService) {
    this.state$ = this.mcpService.state$
  }

  ngOnInit() {
    this.connect()
  }

  ngOnDestroy() {
    this.mcpService.disconnect()
  }

  connect() {
    this.mcpService.connect('https://your-mcp-server.com')
  }

  disconnect() {
    this.mcpService.disconnect()
  }

  async callTool(toolName: string) {
    try {
      const result = await this.mcpService.callTool(toolName)
      console.log('Tool result:', result)
    } catch (error) {
      console.error('Tool call failed:', error)
    }
  }
}

Svelte MCP Store

// lib/mcp.js
import { writable } from 'svelte/store'
import { BrowserOAuthClientProvider } from 'dmcp'
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js'

export const mcpState = writable({
  connected: false,
  tools: [],
  error: null,
  loading: false
})

let client = null
let transport = null

export async function connectMcp(serverUrl, clientName = 'Svelte MCP App') {
  mcpState.update(state => ({ ...state, loading: true, error: null }))

  try {
    const authProvider = new BrowserOAuthClientProvider(serverUrl, {
      clientName
    })

    client = new Client(
      { name: 'svelte-mcp-client', version: '1.0.0' },
      { capabilities: {} }
    )

    transport = new SSEClientTransport(
      new URL(serverUrl),
      { authProvider }
    )

    await client.connect(transport)
    const toolsResponse = await client.request({ method: 'tools/list' })
    
    mcpState.set({
      connected: true,
      tools: toolsResponse.tools,
      loading: false,
      error: null
    })
  } catch (error) {
    mcpState.update(state => ({
      ...state,
      connected: false,
      loading: false,
      error: error.message
    }))
  }
}

export async function callTool(name, args = {}) {
  if (!client) {
    throw new Error('Not connected to MCP server')
  }

  return await client.request({
    method: 'tools/call',
    params: { name, arguments: args }
  })
}

export function disconnectMcp() {
  if (transport) {
    transport.close()
  }
  mcpState.set({
    connected: false,
    tools: [],
    error: null,
    loading: false
  })
}

<!-- McpComponent.svelte -->
<script>
  import { onMount, onDestroy } from 'svelte'
  import { mcpState, connectMcp, callTool, disconnectMcp } from './lib/mcp.js'

  onMount(() => {
    connectMcp('https://your-mcp-server.com')
  })

  onDestroy(() => {
    disconnectMcp()
  })

  async function handleToolCall(toolName) {
    try {
      const result = await callTool(toolName)
      console.log('Tool result:', result)
    } catch (error) {
      console.error('Tool call failed:', error)
    }
  }
</script>

<div>
  {#if $mcpState.loading}
    <div>Connecting to MCP server...</div>
  {:else if $mcpState.error}
    <div class="error">
      Error: {$mcpState.error}
      <button on:click={() => connectMcp('https://your-mcp-server.com')}>
        Retry
      </button>
    </div>
  {:else if $mcpState.connected}
    <div>
      <h2>Available Tools: {$mcpState.tools.length}</h2>
      <ul>
        {#each $mcpState.tools as tool (tool.name)}
          <li>
            {tool.name}
            <button on:click={() => handleToolCall(tool.name)}>
              Call
            </button>
          </li>
        {/each}
      </ul>
      <button on:click={disconnectMcp}>Disconnect</button>
    </div>
  {/if}
</div>

<style>
  .error {
    color: red;
    padding: 10px;
    border: 1px solid red;
    border-radius: 4px;
    margin: 10px 0;
  }
</style>

API Reference

useMcp React Hook

import { useMcp } from 'dmcp/react'

function useMcp(options: UseMcpOptions): UseMcpResult

Options

| Option | Type | Description | |--------|------|-------------| | url | string | Required. URL of your MCP server | | clientName | string | Name of your client for OAuth registration | | clientUri | string | URI of your client for OAuth registration | | callbackUrl | string | Custom callback URL for OAuth redirect (defaults to /oauth/callback on the current origin) | | storageKeyPrefix | string | Storage key prefix for OAuth data in localStorage (defaults to "mcp:auth") | | clientConfig | object | Custom configuration for the MCP client identity | | debug | boolean | Whether to enable verbose debug logging | | autoRetry | boolean \| number | Auto retry connection if initial connection fails, with delay in ms | | autoReconnect | boolean \| number | Auto reconnect if an established connection is lost, with delay in ms (default: 3000) | | transportType | 'auto' \| 'http' \| 'sse' | Transport type preference: 'auto' (HTTP with SSE fallback), 'http' (HTTP only), 'sse' (SSE only) (default: 'auto') |

Return Value

| Property | Type | Description | |----------|------|-------------| | state | string | Current connection state: 'discovering', 'authenticating', 'connecting', 'loading', 'ready', 'failed' | | tools | Tool[] | Available tools from the MCP server | | error | string \| undefined | Error message if connection failed | | authUrl | string \| undefined | Manual authentication URL if popup is blocked | | log | LogEntry[] | Array of log messages | | callTool | (name: string, args?: Record<string, unknown>) => Promise<any> | Function to call a tool on the MCP server | | retry | () => void | Manually attempt to reconnect | | disconnect | () => void | Disconnect from the MCP server | | authenticate | () => void | Manually trigger authentication | | clearStorage | () => void | Clear all stored authentication data |

OAuth Components

The main package exports OAuth authentication components that can be used in any framework:

import { BrowserOAuthClientProvider, onMcpAuthorization } from 'dmcp'

BrowserOAuthClientProvider

new BrowserOAuthClientProvider(serverUrl: string, options?: {
  storageKeyPrefix?: string
  clientName?: string
  clientUri?: string
  callbackUrl?: string
})

onMcpAuthorization

onMcpAuthorization(): Promise<void>

Call this function in your OAuth callback route to handle the authentication response.

License

MIT