Skip to main content

MCP Clients

This guide explains how to use and develop client applications that connect to MCP servers.

Introduction to MCP Clients​

MCP clients are applications that communicate with MCP servers to leverage AI capabilities. Clients can range from simple command-line tools to complex web or mobile applications.

Available Client SDKs​

TRMX AI provides client SDKs for multiple programming languages:

JavaScript/TypeScript

For web, Node.js, and React Native applications

npm install @trmx/client

Python

For data science, backend services, and scripts

pip install trmx-client

Java

For enterprise applications and Android

implementation 'com.trmx:trmx-client:1.0.0'

Go

For high-performance backend services

go get github.com/trmx/client-go

Basic Client Usage​

Here's a basic example of using the JavaScript client:

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

async function main() {
// Initialize the client
  const client = new MCPClient({
    serverUrl: 'https://your-mcp-server.trmx.ai',
    apiKey: 'your-api-key', // Optional, depending on server configuration
  });
  
  // Create a conversation
  const conversation = client.createConversation({
    contextId: 'user-123', // Unique identifier for this conversation
  });
  
  // Send a message
  const response = await conversation.sendMessage('Hello, what can you help me with today?');
  
  console.log('AI response:', response.content);
  
  // Continue the conversation
  const followUpResponse = await conversation.sendMessage('Tell me more about that');
  
  console.log('Follow-up response:', followUpResponse.content);
}

main().catch(console.error);

Authentication​

Depending on your MCP server configuration, you may need to provide authentication:

API Key Authentication​

const client = new MCPClient({
  serverUrl: 'https://your-mcp-server.trmx.ai',
  apiKey: 'your-api-key',
});

OAuth Authentication​

const client = new MCPClient({
  serverUrl: 'https://your-mcp-server.trmx.ai',
  auth: {
    type: 'oauth',
    token: 'your-oauth-token',
  },
});

Working with Tools​

You can call tools exposed by the MCP server:

// List available tools
const tools = await client.request({ method: 'tools/list' });
console.log('Available tools:', tools.result);

// Call a specific tool
const result = await client.request({
  method: 'tools/call',
  params: {
    name: 'calculator',
    arguments: {
      operation: 'add',
      a: 5,
      b: 3,
    },
  },
});

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

Accessing Resources​

You can query resources from the MCP server:

// List available resources
const resources = await client.request({ method: 'resources/list' });
console.log('Available resources:', resources.result);

// Query a specific resource
const documents = await client.request({
  method: 'resources/query',
  params: {
    name: 'documents',
    query: 'product specifications',
  },
});

console.log('Retrieved documents:', documents.result);

Streaming Responses​

For real-time responses, you can use streaming:

// Create a streaming conversation
const streamingConversation = client.createConversation({
  contextId: 'user-456',
  streaming: true,
});

// Send a message with streaming response
const stream = await streamingConversation.sendMessage('Write a short story about space travel');

// Handle streaming chunks
stream.on('data', (chunk) => {
  process.stdout.write(chunk.content);
});

stream.on('end', () => {
  console.log('\n\nStream complete!');
});

stream.on('error', (error) => {
  console.error('Stream error:', error);
});

Error Handling​

Implement proper error handling in your client applications:

try {
  const response = await conversation.sendMessage('Hello');
  console.log('Response:', response.content);
} catch (error) {
  if (error.code === 'RATE_LIMIT_EXCEEDED') {
    console.error('Rate limit exceeded. Please try again later.');
  } else if (error.code === 'CONTEXT_TOO_LARGE') {
    console.error('Conversation context is too large. Please start a new conversation.');
  } else {
    console.error('Error:', error.message);
  }
}

Advanced Client Options​

Timeout Configuration​

const client = new MCPClient({
  serverUrl: 'https://your-mcp-server.trmx.ai',
  timeout: 30000, // 30 seconds
});

Retry Logic​

const client = new MCPClient({
  serverUrl: 'https://your-mcp-server.trmx.ai',
  retry: {
    maxRetries: 3,
    initialDelay: 1000,
    maxDelay: 5000,
  },
});

Custom Headers​

const client = new MCPClient({
  serverUrl: 'https://your-mcp-server.trmx.ai',
  headers: {
    'X-Custom-Header': 'custom-value',
  },
});

Building Custom Clients​

If our provided SDKs don't meet your needs, you can build a custom client using the MCP protocol specification:

  1. Connect to the MCP server endpoint
  2. Use JSON-RPC 2.0 format for requests
  3. Implement proper error handling
  4. Manage conversation context as needed

For detailed protocol specifications, see our API Reference.

Next Steps​