MCP Development Guide

This guide teaches you how to build MCP (Model Context Protocol) servers that integrate your existing APIs with DioscHub.

What You'll Learn

1. What is MCP - Understanding the protocol
2. Diosc Requirements - What Diosc needs beyond standard MCP
3. Authentication - Handling BYOA token forwarding
4. Building Tools - Creating effective AI tools
5. Testing - Validating your MCP server

Quick Overview

What is an MCP Server?

An MCP server is an adapter between AI assistants and your backend systems. It exposes your APIs as "tools" that the AI can use.

Why Build an MCP Server?

Instead of rewriting your APIs for AI consumption, wrap them:

• No API changes - Your existing endpoints work as-is
• Security preserved - User authentication flows through
• AI-friendly interface - Tools have descriptions the AI understands
• Centralized integration - One MCP server per system

Minimal Example

Here's a complete MCP server in TypeScript:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server({
  name: 'orders-api',
  version: '1.0.0'
}, {
  capabilities: {
    tools: {}
  }
});

// Define available tools
server.setRequestHandler('tools/list', async () => ({
  tools: [
    {
      name: 'search_orders',
      description: 'Search for orders by customer name or status',
      inputSchema: {
        type: 'object',
        properties: {
          customer: { type: 'string', description: 'Customer name' },
          status: { type: 'string', enum: ['pending', 'shipped', 'delivered'] }
        }
      }
    }
  ]
}));

// Handle tool calls
server.setRequestHandler('tools/call', async (request) => {
  const { name, arguments: args } = request.params;

  if (name === 'search_orders') {
    // Call your actual API
    const response = await fetch(
      `https://api.example.com/orders?customer=${args.customer}&status=${args.status}`,
      {
        headers: {
          // Forward user's auth (from request headers)
          'Authorization': request.headers?.['authorization']
        }
      }
    );

    const orders = await response.json();
    return { content: [{ type: 'text', text: JSON.stringify(orders) }] };
  }

  throw new Error(`Unknown tool: ${name}`);
});

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);

MCP Server Architecture

Transport Types

MCP supports multiple transports. Diosc uses SSE (Server-Sent Events) over HTTP:

Request Flow

1. User sends message to Diosc
2. AI decides to use a tool
3. Diosc calls your MCP server with:
   • Tool name and arguments
   • User's authentication headers
   • Request context
4. Your MCP server:
   • Validates the request
   • Calls your actual API (with user's auth)
   • Returns the result
5. AI uses the result to respond to the user

Next Steps

1. Understand MCP - Learn the protocol basics
2. Diosc Requirements - What makes Diosc MCP special
3. Handle Authentication - Forward user credentials correctly