Documentation
Tutorials
AGENT_GUIDE API_REFERENCE ARCHITECTURE AUTHENTICATION CHANGELOG EXAMPLES GETTING_STARTED HOSTED_SERVER HTTP_TRANSPORT SECURITY TODO TOOLS_REFERENCE

Tutorial

GETTING_STARTED

Getting Started with MCP Server

This guide helps you connect to the Hiyve MCP server to query your meetings, recordings, and collaboration data through Claude Desktop or custom integrations.

Quick Start: Hosted Server (Recommended)

The fastest way to get started is using our hosted MCP servers. No installation required.

1. Configure Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hiyve": {
      "url": "https://mcp.us-east-1.hiyve.tech/mcp",
      "transport": "streamable-http"
    }
  }
}

2. Restart Claude Desktop

After saving the configuration, restart Claude Desktop.

3. Authenticate

On first connection, Claude Desktop opens a browser window for you to log in. OAuth 2.1 authentication is handled automatically.

4. Start Querying

Ask Claude about your meetings:

"Show my rooms"
"What meetings do I have this week?"
"Summarize my last meeting with the team"
"Who do I collaborate with most?"

For more details, see the Hosted Server Guide.

Self-Hosting the MCP Server

For development or enterprise deployments, you can run your own MCP server.

Prerequisites

  • Node.js 18+
  • MongoDB database
  • OpenAI API key (or xAI API key as fallback)
  • muziertc-models package installed

Installation

Install from the MuzieMedia npm registry:

npm install @muzie/mcp-server --registry=https://s3.us-east-1.amazonaws.com/muzie.media/npm-registry/

Or add to your package.json:

{
  "dependencies": {
    "@muzie/mcp-server": "https://s3.amazonaws.com/muzie.media/npm-registry/muzie-mcp-server/muzie-mcp-server-latest.tgz"
  }
}

Configuration

Initialize the MCP server with dependency injection:

import { createMCPServer } from '@muzie/mcp-server';
import {
  Room, Schedule, Recording, UserProfile,
  StoredRoom, FileIndex, Transcription, Transcribing
} from 'muziertc-models';
import UnifiedAIService from './services/UnifiedAIService.js';
import AISearchService from './services/AISearchService.js';
import GraphContextService from './services/GraphContextService.js';
import { normalizeRoomName } from './utils.js';

// Initialize with all dependencies
const mcp = createMCPServer({
  models: {
    Room,
    Schedule,
    Recording,
    UserProfile,
    StoredRoom,
    FileIndex,
    Transcription,
    Transcribing
  },
  services: {
    UnifiedAIService,
    AISearchService,
    GraphContextService
  },
  utils: {
    normalizeRoomName
  },
  aiConfig: {
    openaiKey: process.env.OPENAI_API_KEY,
    xaiKey: process.env.XAI_API_KEY  // Optional fallback
  }
});

// Export components for use
export const {
  MCPClient,
  SmartRouter,
  primitives,
  ActionTypes,
  toolHandlers,
  buildSecurityContext
} = mcp;

Environment Variables

Variable Required Description
MONGODB_URI Yes MongoDB connection string
OPENAI_API_KEY Yes* OpenAI API key for AI features
XAI_API_KEY No xAI/Grok API key (fallback)
BASE_URL No Server base URL (for OAuth redirects)
OAUTH_LOGIN_URL No OAuth login UI URL

*Either OPENAI_API_KEY or XAI_API_KEY is required for AI features.

Claude Desktop Configuration

Option 1: Hosted Server (Recommended)

Connect to the hosted MCP server:

{
  "mcpServers": {
    "hiyve": {
      "url": "https://mcp.us-east-1.hiyve.tech/mcp",
      "transport": "streamable-http"
    }
  }
}

Available regions:

  • US East: https://mcp.us-east-1.hiyve.tech/mcp
  • US West: https://mcp.us-west-2.hiyve.tech/mcp

Option 2: Self-Hosted via HTTP

Connect to your own MCP server:

{
  "mcpServers": {
    "hiyve": {
      "url": "https://your-server.example.com/mcp",
      "transport": "streamable-http"
    }
  }
}

Option 3: Local via Stdio

For local development, use stdio transport:

{
  "mcpServers": {
    "hiyve": {
      "command": "node",
      "args": ["/path/to/your/mcp-server.js"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/muzie",
        "OPENAI_API_KEY": "sk-...",
        "USER_EMAIL": "your@email.com",
        "API_KEY": "your_org_id"
      }
    }
  }
}

Basic Usage

Direct Tool Calls

Call tools directly using toolHandlers:

import { toolHandlers, buildSecurityContext } from './mcp/index.js';

// Build security context for the user
const userContext = {
  email: 'user@example.com',
  userId: 'user_example_com',  // Cleaned email format
  apiKey: 'org_123456',        // Organization/tenant ID
  isAdmin: false,
  timezone: 'America/New_York'
};

const securityContext = await buildSecurityContext(userContext);

// Call a tool directly
const result = await toolHandlers.query_rooms({
  limit: 10,
  apiKey: userContext.apiKey,
  userId: userContext.userId,
  _userContext: securityContext
});

console.log(result);
// { success: true, rooms: [...], total: 42 }

Using Smart Router

Route queries to the appropriate handler:

import { smartRouter, RouteType } from './mcp/index.js';

const query = "Show me my meetings from last week";
const analysis = smartRouter.analyze(query);

console.log(analysis);
// {
//   route: 'SIMPLE',
//   tool: 'query_rooms',
//   params: { startDate: '2026-01-04', endDate: '2026-01-11' },
//   confidence: 0.95
// }

switch (analysis.route) {
  case RouteType.DIRECT:
    // Single action, execute immediately
    break;
  case RouteType.SIMPLE:
    // Database query, use tool directly
    break;
  case RouteType.AGENT:
    // Complex query, use MCPAgentOrchestrator
    break;
}

Using the Agent for Complex Queries

import { handleAgentQuery, shouldUseAgent } from './mcp/index.js';

const query = "Find all my meetings with John and summarize what we discussed";

if (shouldUseAgent(query)) {
  const result = await handleAgentQuery(query, userContext, {
    maxIterations: 5,
    timeout: 30000
  });

  console.log(result.response);
  // Formatted markdown response with meeting summaries
}

Express Integration

Mount MCP routes in your Express app:

import express from 'express';
import { toolHandlers, buildSecurityContext, ActionTypes } from './mcp/index.js';

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

// MCP command endpoint
app.post('/api/mcp/command', async (req, res) => {
  try {
    const { query } = req.body;
    const userContext = req.user;  // From your auth middleware

    // Build security context
    const securityContext = await buildSecurityContext(userContext);

    // Route and execute the query
    const result = await handleQuery(query, securityContext);

    res.json({
      success: true,
      data: result.data,
      actionType: result.actionType || ActionTypes.INFO_ONLY
    });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});

app.listen(3001);

Next Steps