Quick Start

Create your first MCP connection and start using tools in under 5 minutes.

Basic Connection

The simplest way to connect to an MCP server is using the stdio transport:

import { MCPClient } from '@omnimcp/client';

// Create a client instance
const client = new MCPClient('my-app', '1.0.0');

// Connect to a local MCP server
await client.connect({
  type: 'stdio',
  options: {
    command: 'node',
    args: ['path/to/mcp-server.js']
  }
});

console.log('Connected to:', client.serverInfo);

Listing Available Tools

Once connected, you can discover what tools the server provides:

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

tools.forEach(tool => {
  console.log(`Tool: ${tool.name}`);
  console.log(`  Description: ${tool.description}`);
  console.log(`  Parameters: ${JSON.stringify(tool.inputSchema)}`);
});

Calling Tools

Execute tools with type-safe parameters:

// Call a tool
const result = await client.tools.call({
  name: 'get_weather',
  arguments: {
    city: 'San Francisco',
    units: 'celsius'
  }
});

console.log('Weather:', result);

AI-Powered Tool Usage

Let AI intelligently select and use tools based on natural language:

import { MCPClientWithAI } from '@omnimcp/client/providers';

// Create AI-enabled client
const aiClient = new MCPClientWithAI('my-app', '1.0.0', {
  apiKey: process.env.OPENAI_API_KEY,
  provider: 'openai'
});

// Connect to server
await aiClient.connect({
  type: 'stdio',
  options: { command: 'mcp-server' }
});

// Let AI handle the tool selection and execution
const response = await aiClient.queryAI(
  "What's the weather like in Tokyo right now?",
  { model: 'gpt-4' }
);

console.log('AI Response:', response);

Error Handling

OmniMCP provides comprehensive error handling with helpful messages:

import { ConnectionError, TimeoutError } from '@omnimcp/core';

try {
  await client.connect(config);
} catch (error) {
  if (error instanceof ConnectionError) {
    console.error('Connection failed:', error.getUserMessage());
    // Retry logic here
  } else if (error instanceof TimeoutError) {
    console.error('Connection timed out:', error.getUserMessage());
  } else {
    console.error('Unexpected error:', error);
  }
}

Using Different Transports

HTTP Transport

await client.connect({
  type: 'http',
  options: {
    url: 'https://api.example.com/mcp'
  }
});

Server-Sent Events (SSE)

await client.connect({
  type: 'sse',
  options: {
    url: 'https://api.example.com/mcp/sse'
  }
});

Complete Example

Here`s a complete example that puts it all together:

import { MCPClientWithAI } from '@omnimcp/client/providers';
import { retry } from '@omnimcp/core';

async function main() {
  // Create client with AI support
  const client = new MCPClientWithAI('weather-app', '1.0.0', {
    apiKey: process.env.OPENAI_API_KEY,
    provider: 'openai'
  });

  try {
    // Connect with retry logic
    await retry(
      () => client.connect({
        type: 'stdio',
        options: {
          command: 'weather-mcp-server'
        }
      }),
      { maxAttempts: 3 }
    );

    console.log('Connected successfully!');

    // Query weather using natural language
    const weather = await client.queryAI(
      "Compare the weather in Tokyo and London",
      { model: 'gpt-4' }
    );

    console.log(weather);

  } catch (error) {
    console.error('Error:', error.getUserMessage?.() || error.message);
  } finally {
    // Clean up
    await client.disconnect();
  }
}

main().catch(console.error);

Next Steps

• Learn about MCP concepts
• Explore advanced usage patterns
• Check out the API reference
• View more examples