@divinci-ai/mcp

MCP (Model Context Protocol) SDK for integrating with AI assistants like Claude Desktop and Cursor

Installation

npm install @divinci-ai/mcp
# or
pnpm add @divinci-ai/mcp
# or
yarn add @divinci-ai/mcp

Quick Start

import { McpClient } from "@divinci-ai/mcp";

const client = new McpClient({
  serverUrl: "https://mcp.divinci.app",
  apiKey: "divinci_key_...",
});

// Connect to the MCP server
await client.connect();

// List available tools
const tools = await client.listTools();

// Call a tool
const result = await client.callTool("search_knowledge", {
  query: "return policy",
});

Features

• SSE Transport - Real-time server-sent events for MCP communication
• Auth0 Integration - PKCE OAuth flow for browser authentication
• Tool Invocation - Call MCP tools with typed arguments
• x402 Payments - Automatic payment handling for premium tools
• Reconnection - Automatic reconnection with exponential backoff
• TypeScript - Full type safety with comprehensive type definitions

Usage

Connecting to MCP Server

const client = new McpClient({
  serverUrl: "https://mcp.divinci.app",
  apiKey: "divinci_key_...",
});

// Listen for connection events
client.on("connected", () => console.log("Connected!"));
client.on("disconnected", () => console.log("Disconnected"));
client.on("error", (error) => console.error("Error:", error));

await client.connect();

Tool Operations

// List all available tools
const tools = await client.listTools();
for (const tool of tools) {
  console.log(`${tool.name}: ${tool.description}`);
  if (tool.pricing) {
    console.log(`  Price: $${tool.pricing.priceUsd}`);
  }
}

// Call a tool
const result = await client.callTool("search_knowledge", {
  query: "How do I reset my password?",
  limit: 5,
});
console.log(result.content);

// Get a specific tool's details
const tool = await client.getTool("send_message");

Building Custom Tools

import { ToolBuilder } from "@divinci-ai/mcp";

const searchTool = new ToolBuilder("advanced_search")
  .describe("Search with advanced filters")
  .addString("query", { required: true, description: "Search query" })
  .addNumber("limit", { description: "Max results", default: 10 })
  .addBoolean("exact", { description: "Exact match only" })
  .addArray("categories", "string", { description: "Filter categories" })
  .build();

console.log(searchTool.inputSchema);

x402 Payment Handling

import { McpClient, PaymentRequiredError } from "@divinci-ai/mcp";

const client = new McpClient({
  serverUrl: "https://mcp.divinci.app",
  apiKey: "divinci_key_...",
  x402: {
    autoPayment: true,
    maxPaymentUsd: 1.0,
    wallet: {
      getAddress: async () => "0x...",
      pay: async (details) => {
        // Execute payment
        return { transactionHash: "0x...", signature: "..." };
      },
    },
  },
});

// Tool calls automatically handle payment
const result = await client.callTool("premium_search", { query: "test" });

Manual Payment Flow

try {
  await client.callTool("premium_search", { query: "test" });
} catch (error) {
  if (error instanceof PaymentRequiredError) {
    console.log(`Payment required: $${error.paymentDetails.amountUsd}`);
    console.log(`Recipient: ${error.paymentDetails.recipient}`);
    console.log(`Network: ${error.paymentDetails.network}`);

    // Handle payment manually
    const receipt = await processPayment(error.paymentDetails);

    // Retry with payment proof
    const result = await client.callTool("premium_search", {
      query: "test",
      _payment: receipt,
    });
  }
}

Auth0 Browser Authentication

import { Auth0Handler } from "@divinci-ai/mcp";

const auth = new Auth0Handler({
  domain: "auth.divinci.app",
  clientId: "your-client-id",
  redirectUri: window.location.origin + "/callback",
  audience: "https://api.divinci.app",
});

// Start login flow
await auth.login();

// Handle callback (on redirect URI)
const tokens = await auth.handleCallback();

// Use tokens with MCP client
const client = new McpClient({
  serverUrl: "https://mcp.divinci.app",
  getToken: () => auth.getAccessToken(),
});

SSE Transport Direct Usage

import { SseTransport } from "@divinci-ai/mcp";

const transport = new SseTransport({
  url: "https://mcp.divinci.app/sse",
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
});

transport.on("connected", () => console.log("Connected"));
transport.on("message", (msg) => console.log("Message:", msg));
transport.on("error", (err) => console.error("Error:", err));

await transport.connect();

// Send a request
const response = await transport.request("tools/list");

Configuration

const client = new McpClient({
  // Required
  serverUrl: "https://mcp.divinci.app",

  // Authentication (one of these)
  apiKey: "divinci_key_...",
  getToken: async () => await fetchAccessToken(),

  // Optional
  timeout: 30000,
  reconnect: true,
  maxReconnectAttempts: 5,

  // x402 Payment Configuration
  x402: {
    autoPayment: false,
    maxPaymentUsd: 1.0,
    network: "base",
    wallet: myWallet,
  },
});

API Reference

McpClient

| Method | Description | |--------|-------------| | connect() | Connect to MCP server | | disconnect() | Disconnect from server | | listTools() | List available tools | | getTool(name) | Get tool by name | | callTool(name, args) | Call a tool | | on(event, handler) | Listen for events | | off(event, handler) | Remove event listener |

McpClient Events

| Event | Description | |-------|-------------| | connected | Connected to server | | disconnected | Disconnected from server | | reconnecting | Attempting reconnection | | error | Error occurred | | message | Message received |

SseTransport

| Method | Description | |--------|-------------| | connect() | Open SSE connection | | disconnect() | Close connection | | request(method, params?) | Send JSON-RPC request | | notify(method, params?) | Send notification | | getState() | Get connection state |

Auth0Handler

| Method | Description | |--------|-------------| | login() | Start login flow | | logout() | Clear tokens and logout | | handleCallback() | Handle OAuth callback | | getAccessToken() | Get current access token | | refreshToken() | Refresh access token | | getUserInfo() | Get authenticated user info |

ToolBuilder

| Method | Description | |--------|-------------| | describe(description) | Set tool description | | addString(name, options?) | Add string parameter | | addNumber(name, options?) | Add number parameter | | addBoolean(name, options?) | Add boolean parameter | | addArray(name, itemType, options?) | Add array parameter | | build() | Build tool schema |

Error Types

| Error | Description | |-------|-------------| | PaymentRequiredError | x402 payment required for tool |

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "divinci": {
      "url": "https://mcp.divinci.app/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

Cursor

Add to Cursor settings:

{
  "mcp.servers": {
    "divinci": {
      "url": "https://mcp.divinci.app/sse",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

What is MCP?

The Model Context Protocol (MCP) is an open standard introduced by Anthropic that standardizes how AI systems integrate with external tools and data sources. It enables AI assistants to:

• Call external tools with structured arguments
• Access resources and data from external systems
• Maintain context across conversations
• Support payment for premium tools via x402

Learn more at modelcontextprotocol.io

Related Packages

• @divinci-ai/client - Browser SDK for chat integration
• @divinci-ai/server - Node.js SDK for server-side operations
• @divinci-ai/types - Shared TypeScript type definitions

Documentation

Full documentation available at sdk.divinci.ai

License

MIT