Model Context Protocol (MCP)

Standardized protocol for LLM tool access and context sharing

The MCP package provides a complete implementation of the Model Context Protocol, enabling interoperability between LLMs and external tools, resources, and prompts.

Installation

npm install @orka-js/mcp
# or
pnpm add @orka-js/mcp

Features

MCP Client

Connect to any MCP-compatible server

MCP Server

Expose tools, resources, and prompts via MCP

MCP Gateway

Route requests to multiple upstream servers

Auto-discovery

Automatically discover tools from connected servers

Authentication

API key support for secure connections

Health checks

Automatic upstream health monitoring

#MCP Client

Connect to MCP servers and access their tools, resources, and prompts.

import { MCPClient } from '@orka-js/mcp';
 
const client = new MCPClient({
  endpoint: 'http://localhost:3000/mcp',
  apiKey: process.env.MCP_API_KEY,
});
 
await client.connect();
 
// List available tools
const tools = await client.listTools();
console.log('Available tools:', tools.map(t => t.name));
 
// Call a tool
const result = await client.callTool('get_customer', { id: '123' });
console.log('Result:', result);
 
// Read a resource
const contents = await client.readResource('file:///data/config.json');
 
// Get a prompt
const messages = await client.getPrompt('greeting', { name: 'John' });

#MCP Server

Expose your own tools, resources, and prompts via the MCP protocol.

import { MCPServer } from '@orka-js/mcp';
 
const server = new MCPServer({
  name: 'my-mcp-server',
  port: 3000,
  apiKey: process.env.MCP_API_KEY,
});
 
// Register a tool
server.tool('get_customer', {
  description: 'Get customer by ID',
  inputSchema: {
    type: 'object',
    properties: {
      id: { type: 'string', description: 'Customer ID' }
    },
    required: ['id']
  }
}, async (args) => {
  const customer = await db.customers.findById(args.id);
  return {
    success: true,
    content: [{ type: 'text', text: JSON.stringify(customer) }]
  };
});
 
// Register a resource
server.resource('file:///data/config.json', {
  name: 'Configuration',
  description: 'Application configuration',
  mimeType: 'application/json'
}, async (uri) => {
  const config = await fs.readFile('./config.json', 'utf-8');
  return [{ type: 'text', text: config }];
});
 
await server.start();

#MCP Gateway

Aggregate multiple MCP servers behind a single endpoint with load balancing.

import { MCPGateway } from '@orka-js/mcp';
 
const gateway = new MCPGateway({
  name: 'my-gateway',
  port: 4000,
  upstreams: [
    { name: 'crm', endpoint: 'http://localhost:3001/mcp' },
    { name: 'erp', endpoint: 'http://localhost:3002/mcp' },
    { name: 'docs', endpoint: 'http://localhost:3003/mcp' },
  ],
});
 
await gateway.start();
 
// Check upstream status
const status = gateway.getUpstreamStatus();
console.log('Upstreams:', status);

Integration with Agents

Use MCP tools with OrkaJS agents for powerful agentic workflows.

import { ReActAgent } from '@orka-js/agent';
import { MCPClient } from '@orka-js/mcp';
 
// Connect to MCP server
const mcp = new MCPClient({ endpoint: 'http://localhost:3000/mcp' });
await mcp.connect();
 
// Get tools from MCP
const mcpTools = await mcp.listTools();
 
// Convert MCP tools to OrkaJS tools
const tools = mcpTools.map(t => ({
  name: t.name,
  description: t.description,
  parameters: t.inputSchema.properties,
  execute: async (args) => {
    const result = await mcp.callTool(t.name, args);
    return result.content[0]?.text || '';
  }
}));
 
// Create agent with MCP tools
const agent = new ReActAgent({
  llm,
  tools,
  maxIterations: 10,
});
 
const result = await agent.run('Get customer 123 and summarize their orders');

Complete Examples

Example 1: Weather Service with MCP Server

A complete weather service that exposes tools, resources, and prompts via MCP:

import { MCPServer } from '@orka-js/mcp';
import express from 'express';
 
// Create MCP server
const server = new MCPServer({
  name: 'weather-service',
  version: '1.0.0',
  description: 'Weather data and forecasts'
});
 
// Add weather tool
server.addTool({
  name: 'get_weather',
  description: 'Get current weather for a location',
  parameters: [
    { name: 'location', type: 'string', description: 'City name', required: true },
    { name: 'units', type: 'string', description: 'Temperature units (celsius/fahrenheit)', required: false }
  ],
  execute: async (args) => {
    const { location, units = 'celsius' } = args;
    // Call weather API
    const weather = await fetchWeatherData(location);
    return {
      output: JSON.stringify({
        location,
        temperature: units === 'celsius' ? weather.temp: (weather.temp * 9/5) + 32,
        condition: weather.condition,
        humidity: weather.humidity,
        units
      })
    };
  }
});
 
// Add forecast tool
server.addTool({
  name: 'get_forecast',
  description: 'Get 5-day weather forecast',
  parameters: [
    { name: 'location', type: 'string', description: 'City name', required: true }
  ],
  execute: async (args) => {
    const forecast = await fetchForecast(args.location);
    return { output: JSON.stringify(forecast) };
  }
});
 
// Add weather resource
server.addResource({
  uri: 'weather://current',
  name: 'Current Weather Data',
  description: 'Real-time weather information',
  mimeType: 'application/json',
  read: async () => {
    const data = await fetchGlobalWeather();
    return { content: JSON.stringify(data) };
  }
});
 
// Add weather prompt template
server.addPrompt({
  name: 'weather_report',
  description: 'Generate a weather report',
  arguments: [
    { name: 'location', description: 'City name', required: true }
  ],
  template: async (args) => ({
    messages: [
      {
        role: 'system',
        content: 'You are a professional meteorologist providing weather reports.'
      },
      {
        role: 'user',
        content: `Provide a detailed weather report for ${args.location}. Include current conditions, forecast, and recommendations.`
      }
    ]
  })
});
 
// Start MCP server
const app = express();
server.attach(app);
app.listen(3001, () => {
  console.log('Weather MCP Server running on port 3001');
});
 
async function fetchWeatherData(location: string) {
  // Implementation
  return { temp: 22, condition: 'Sunny', humidity: 65 };
}
 
async function fetchForecast(location: string) {
  // Implementation
  return { days: [] };
}
 
async function fetchGlobalWeather() {
  // Implementation
  return { regions: [] };
}

Example 2: Multi-Service Gateway

Aggregate multiple MCP servers through a single gateway:

import { MCPGateway } from '@orka-js/mcp';
import express from 'express';
 
// Create gateway
const gateway = new MCPGateway({
  name: 'enterprise-gateway',
  version: '1.0.0'
});
 
// Add upstream services
gateway.addUpstream({
  name: 'weather-service',
  url: 'http://localhost:3001',
  healthCheck: '/health'
});
 
gateway.addUpstream({
  name: 'database-service',
  url: 'http://localhost:3002',
  healthCheck: '/health'
});
 
gateway.addUpstream({
  name: 'analytics-service',
  url: 'http://localhost:3003',
  healthCheck: '/health'
});
 
// Start gateway
const app = express();
gateway.attach(app);
 
app.listen(4000, () => {
  console.log('MCP Gateway running on port 4000');
  console.log('Aggregating services: weather, database, analytics');
});
 
// Client usage
import { MCPClient } from '@orka-js/mcp';
 
const client = new MCPClient({
  serverUrl: 'http://localhost:4000'
});
 
await client.connect();
 
// List all tools from all services
const tools = await client.listTools();
console.log('Available tools:', tools.map(t => t.name));
 
// Call tool from any service
const weather = await client.callTool('get_weather', {
  location: 'Paris'
});
 
const dbQuery = await client.callTool('query_database', {
  sql: 'SELECT * FROM users LIMIT 10'
});
 
const analytics = await client.callTool('get_metrics', {
  period: 'last_7_days'
});

Example 3: Agent with MCP Tools

Create an intelligent agent that uses MCP tools dynamically:

import { MCPClient } from '@orka-js/mcp';
import { ReActAgent } from '@orka-js/agent';
import { OpenAIAdapter } from '@orka-js/openai';
 
// Connect to MCP gateway
const mcpClient = new MCPClient({
  serverUrl: 'http://localhost:4000'
});
await mcpClient.connect();
 
// Get all available tools
const mcpTools = await mcpClient.listTools();
 
// Convert MCP tools to agent tools
const agentTools = mcpTools.map(tool => ({
  name: tool.name,
  description: tool.description,
  parameters: tool.inputSchema.properties,
  execute: async (args: Record<string, unknown>) => {
    const result = await mcpClient.callTool(tool.name, args);
    return { output: result.content };
  }
}));
 
// Create agent with MCP tools
const llm = new OpenAIAdapter({
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4'
});
 
const agent = new ReActAgent(
  {
    goal: 'Help users with weather, database queries, and analytics',
    tools: agentTools,
    maxSteps: 10
  },
  llm
);
 
// Use the agent
const result = await agent.run(
  'What is the weather in Paris and how many users signed up in the last 7 days?'
);
 
console.log('Agent response:', result.output);
console.log('Steps taken:', result.steps?.length);
console.log('Tools used:', result.steps?.map(s => s.action?.tool));
 
// Example output:
// Agent response: "The weather in Paris is currently 22°C and sunny. 
//                  In the last 7 days, 1,234 new users signed up."
// Steps taken: 4
// Tools used: ['get_weather', 'query_database', 'get_metrics']