@orbitalmcp/sdk

Connect to any MCP server with 2 lines of code

OrbitalMCP Agent SDK provides a simple, unified API for discovering and connecting to any Model Context Protocol (MCP) server. No configuration needed - just import and use.

Features

• 🔍 Auto-Discovery: Find MCP servers by capability, category, or name
• 🚀 Universal Gateway: Invoke any MCP server via HTTP (no local installation)
• 🎯 Simple API: 2-line integration for AI agents
• 📦 567+ Servers: Access to entire OrbitalMCP registry
• ⚡ Parallel Execution: Batch requests to multiple servers
• 🔒 Type-Safe: Full TypeScript support
• 🌐 Cross-Platform: Works in Node.js and browsers

Installation

npm install @orbitalmcp/sdk

Quick Start

Simple 2-Line Integration

import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient();

// Discover and invoke in one call
const result = await client.discover("github", "search_repos", {
  query: "mcp",
});

console.log(result);

Direct Server Invocation

import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient();

// Invoke a known server
const result = await client.invoke("Airbnb", "airbnb_search", {
  location: "New York",
  checkin: "2025-11-01",
  checkout: "2025-11-05",
});

console.log(result);

API Reference

OrbitalClient

The main unified client that combines registry discovery and gateway invocation.

Constructor

new OrbitalClient(options?: ClientOptions)

Options:

• registryUrl?: string - Custom registry URL (default: OrbitalMCP public registry)
• gatewayUrl?: string - Custom gateway URL (default: OrbitalMCP public gateway)
• timeout?: number - Request timeout in ms (default: 30000)
• apiKey?: string - API key for authenticated requests

Methods

discover(query, tool, args, options?)

Discover and invoke a tool in one call. Automatically finds a server matching the query and invokes the tool.

const result = await client.discover("github", "search_repos", {
  query: "mcp",
});

invoke(server, tool, args, options?)

Invoke a tool on a known server.

const result = await client.invoke("Airbnb", "airbnb_search", {
  location: "San Francisco",
});

search(filters)

Search for servers with filters.

const servers = await client.search({
  category: "ai",
  capability: "search",
  limit: 10,
});

Filters:

• capability?: string - Filter by capability (e.g., 'search', 'read', 'write')
• category?: string - Filter by category (e.g., 'ai', 'database', 'productivity')
• q?: string - Text search query
• tag?: string - Filter by tag
• sort?: 'rating' | 'installs' | 'name' | 'created' | 'stars'
• order?: 'asc' | 'desc'
• limit?: number - Max results
• offset?: number - Pagination offset

getServer(identifier)

Get details about a specific server.

const server = await client.getServer("Airbnb");
console.log(server.tools); // List all available tools

listTools(server)

List available tools for a server.

const tools = await client.listTools("Airbnb");
// [{ name: 'airbnb_search', description: '...', arguments: {...} }]

findByCapability(capability)

Find servers by capability.

const servers = await client.findByCapability("search");

findByCategory(category)

Find servers by category.

const servers = await client.findByCategory("ai");

batch(requests, options?)

Invoke multiple tools in parallel.

const results = await client.batch([
  {
    server: "Airbnb",
    tool: "airbnb_search",
    arguments: { location: "NYC" },
  },
  {
    server: "GitHub",
    tool: "search_repos",
    arguments: { query: "mcp" },
  },
]);

getCapabilities()

Get all available capabilities in the registry.

const capabilities = await client.getCapabilities();
// ['read', 'write', 'search', 'update', 'delete', 'analyze', 'execute']

getCategories()

Get all categories with server counts.

const categories = await client.getCategories();
// [{ category: 'ai', count: '164' }, { category: 'development', count: '92' }, ...]

getStats()

Get registry statistics.

const stats = await client.getStats();
// { total_servers: 567, total_capabilities: 7, ... }

RegistryClient

Low-level client for registry discovery (automatically used by OrbitalClient).

import { RegistryClient } from "@orbitalmcp/sdk";

const registry = new RegistryClient();
const servers = await registry.search({ category: "ai" });

GatewayClient

Low-level client for gateway invocation (automatically used by OrbitalClient).

import { GatewayClient } from "@orbitalmcp/sdk";

const gateway = new GatewayClient();
const result = await gateway.invoke("Airbnb", "airbnb_search", {
  location: "New York",
});

Examples

AI Agent Integration

import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient();

// AI agent needs to search GitHub
async function handleUserRequest(userQuery) {
  if (userQuery.includes("search github")) {
    const result = await client.discover("github", "search_repos", {
      query: extractQuery(userQuery),
    });

    return formatResponse(result);
  }
}

Multi-Server Search

import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient();

// Search multiple travel sites in parallel
const results = await client.batch([
  { server: "Airbnb", tool: "airbnb_search", arguments: { location: "Paris" } },
  { server: "Hotels", tool: "search_hotels", arguments: { city: "Paris" } },
  {
    server: "Flights",
    tool: "search_flights",
    arguments: { destination: "Paris" },
  },
]);

// Combine and present results

Dynamic Server Discovery

import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient();

// Find all servers that can search
const searchServers = await client.findByCapability("search");

console.log(`Found ${searchServers.length} servers with search capability`);

// Use the first one
const result = await client.invoke(
  searchServers[0].name,
  searchServers[0].tools[0].name,
  { query: "example" }
);

Category Browsing

import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient();

// Get all AI servers
const aiServers = await client.findByCategory("ai");

// Get all database servers
const dbServers = await client.findByCategory("database");

// Get all productivity servers
const productivityServers = await client.findByCategory("productivity");

TypeScript Support

Full TypeScript definitions included:

import { OrbitalClient, McpServer, InvokeResult } from "@orbitalmcp/sdk";

const client = new OrbitalClient();

const server: McpServer = await client.getServer("Airbnb");
const result: InvokeResult = await client.invoke("Airbnb", "airbnb_search", {
  location: "Tokyo",
});

Advanced Configuration

Custom Registry/Gateway URLs

import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient({
  registryUrl: "https://custom-registry.example.com/api/registry/v1",
  gatewayUrl: "https://custom-gateway.example.com/api/gateway",
  timeout: 60000, // 60 seconds
  apiKey: "your-api-key",
});

Authentication

import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient({ apiKey: "your-api-key" });

// API key is automatically included in all requests
const result = await client.invoke("SecureServer", "protected_tool", {});

Error Handling

import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient();

try {
  const result = await client.invoke("Airbnb", "airbnb_search", {
    location: "New York",
  });

  if (result.success) {
    console.log("Success:", result.result);
  }
} catch (error) {
  console.error("Failed to invoke tool:", error.message);
}

Architecture

OrbitalMCP SDK consists of three main components:

1. Registry Client: Discovers MCP servers from the OrbitalMCP registry (567+ servers)
2. Gateway Client: Invokes tools on any MCP server via HTTP
3. Unified Client: High-level API combining discovery and invocation

┌─────────────┐
│  Your App   │
└──────┬──────┘
       │
       │ @orbitalmcp/sdk
       │
┌──────▼──────────────────────────┐
│     OrbitalClient               │
│  ┌──────────┐   ┌─────────────┐│
│  │ Registry │   │   Gateway   ││
│  │  Client  │   │   Client    ││
│  └────┬─────┘   └──────┬──────┘│
└───────┼────────────────┼───────┘
        │                │
        │                │
┌───────▼──────┐  ┌──────▼───────┐
│   Registry   │  │   Gateway    │
│   Service    │  │   Service    │
│ (567 servers)│  │ (Universal   │
│              │  │  Proxy)      │
└──────────────┘  └──────────────┘

Browser Support

The SDK works in browsers with a bundler (Webpack, Vite, etc.):

import { OrbitalClient } from "@orbitalmcp/sdk";

const client = new OrbitalClient();

// Works in browser - all calls go through HTTP gateway
const result = await client.invoke("Airbnb", "airbnb_search", {
  location: "London",
});

License

MIT

AI Agent Integration

OrbitalMCP SDK enables seamless integration with popular AI agents and development tools.

Claude Desktop Integration

Add OrbitalMCP to Claude Desktop using the MCP server bridge:

1. Setup the bridge server:

npm install @orbitalmcp/sdk
# Copy orbitalmcp-mcp-server.js from sdk/examples/

2. Configure Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "orbitalmcp": {
      "command": "node",
      "args": ["/path/to/orbitalmcp-mcp-server.js"]
    }
  }
}

3. Claude can now access 567+ MCP servers:

"Hey Claude, search GitHub for MCP servers"
"Hey Claude, find Airbnb listings in Paris"
"Hey Claude, search Linear for issues"

GPT Actions Integration

Configure GPT Actions with the OrbitalMCP OpenAPI spec:

1. Upload the API specification:

   • Go to OpenAI's GPT Actions configuration
   • Upload gpt-actions-openapi.yaml from this package
   • Set authentication headers if needed

2. GPT can now invoke any MCP server:

"Search for GitHub repos about MCP"
"Find Airbnb listings in Tokyo"
"Query Git operations on a repository"

Custom Agent Integration

Use the SDK directly in your agent code:

import { OrbitalClient } from "@orbitalmcp/sdk";

class MyAgent {
  constructor() {
    this.mcpClient = new OrbitalClient();
  }

  async searchKnowledge(query) {
    // Search across multiple MCP servers
    return await this.mcpClient.discover("github", "search_repos", { query });
  }

  async getTravelInfo(location) {
    // Parallel search multiple travel APIs
    return await this.mcpClient.batch([
      { server: "Airbnb", tool: "airbnb_search", arguments: { location } },
      {
        server: "Hotels",
        tool: "search_hotels",
        arguments: { city: location },
      },
    ]);
  }
}

Links

• OrbitalMCP Website
• API Documentation
• Registry Browser
• Examples
• Integration Guides
• GitHub

Support

• Email: [email protected]