Install

npm install mcpboss

Quick Start SDK

import { McpBoss } from 'mcpboss';
const client = new McpBoss();

// Agents
await client.query('Current weather?');
await client.query('Weather tomorrow?', {
  limitTools: ['getWeather'],
});

// List MCP Servers
await client.api.getMcpServers();

Quick Start CLI

npm i -g mcpboss
mcpboss config login # login
mcpboss hosted ls # list hosted tools

Package & Upload Hosted Tool

mkdir pkg
echo 'export const schema = {}' > pkg/index.js
mcpboss hosted deploy pgk

Configuration

This is the default configuration lookup strategy:

1. Passed options (only SDK)
2. Environment variables MCPBOSS_ORG_ID and MCPBOSS_API_KEY
3. Configurations from ~/.mcpboss.config in the following order
   1. MCPBOSS_ORG_ID
   2. The default organization

SDK

Authentication can be controlled in the constructor by providing a custom ConfigLoader:

const client = new McpBoss({ configLoader: ConfigLoader });

The configLoader must follow this shape:

{
  getConfig(): { baseUrl: string; token: () => Promise<string> } | null;
}

Agent Usage

Basic Query

const response = await client.query('Hello, how are you?');

if (response.type === 'success') {
  console.log(response.text);
  console.log(response.fullOutput); // Complete API response
} else {
  console.error('Error:', response.text);
}

Advanced Query Options

const response = await client.query('Search for recent news about AI', {
  agentId: 'specific-agent-id', // Use a specific agent
  modelId: 'gpt-4', // Use a specific model
  llmApiKeyId: 'my-openai-key', // Use a specific API key
  limitMcpServers: ['news-server'], // Limit to specific MCP servers
  limitTools: ['brave_news_search'], // Limit to specific tools
  dontAutoCreateAgent: false, // Prevent auto-creation of agents
  timeoutInMilliseconds: 300e3, // Wait maximum 5 minutes for LLM generation
});

Agent Management

The SDK automatically handles agent selection and creation with intelligent fallback logic:

1. Exact Match: If agentId is provided, uses that specific agent
2. Model + API Key: Finds agent matching both modelId and llmApiKeyId
3. Model Only: Finds agent matching modelId
4. API Key Only: Finds agent matching llmApiKeyId
5. Auto-Create: Creates a new agent if none match (unless dontAutoCreateAgent is true)
6. Fallback: Uses the first available agent if no criteria specified

When auto-creating agents, the SDK will:

• Prefer the specified modelId if available
• Fall back to GPT-5 if available
• Use the first available model as a last resort
• Apply the specified llmApiKeyId or use the default

Debugging

The SDK uses the debug package for logging. Enable debug output with:

DEBUG=mcpboss node your-script.js

License

MIT License - see LICENSE file for details.

Contributing

We welcome contributions!

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request