---
title: "Options"
description: "Complete API reference for the Integrate SDK"
---
## createMCPClient
Creates a new MCP client instance.
```typescript
function createMCPClient(config: MCPClientConfig): MCPClient;
```
### Parameters
### Returns
An `MCPClient` instance.
### Example
```typescript
const client = createMCPClient({
integrations: [
githubIntegration({
clientId: process.env.GITHUB_CLIENT_ID!,
clientSecret: process.env.GITHUB_CLIENT_SECRET!,
}),
],
timeout: 60000,
headers: {
"User-Agent": "my-app/1.0.0",
},
clientInfo: {
name: "my-app",
version: "1.0.0",
},
});
```
## MCPClient
The main client class for interacting with the MCP server.
### connect()
Establishes connection to the MCP server.
```typescript
async connect(): Promise
```
**Example:**
```typescript
await client.connect();
```
### disconnect()
Closes the connection to the MCP server.
```typescript
async disconnect(): Promise
```
**Example:**
```typescript
await client.disconnect();
```
### Typed Integration Methods
Built-in integrations (GitHub, Gmail) provide fully typed methods for calling tools.
**GitHub Integration Methods:**
```typescript
client.github.createIssue(params);
client.github.listIssues(params);
client.github.getRepo(params);
client.github.createPullRequest(params);
// ... and more
```
**Gmail Integration Methods:**
```typescript
client.gmail.sendEmail(params);
client.gmail.listEmails(params);
client.gmail.searchEmails(params);
client.gmail.createLabel(params);
// ... and more
```
**Server Methods:**
```typescript
client.server.listToolsByIntegration(params);
client.server.listAllProviders();
client.server.listConfiguredIntegrations();
// ... other server-level tools
```
**Example:**
```typescript
// Fully typed with IntelliSense support
const result = await client.github.createIssue({
owner: "owner",
repo: "repo",
title: "Bug report",
body: "Description",
});
```
### \_callToolByName()
For integrations configured with `genericOAuthIntegration` or `createSimpleIntegration`, use this internal method to call tools directly.
```typescript
async _callToolByName(name: string, args?: Record): Promise
```
**Parameters:**
- `name` - Full tool name (e.g., 'slack_send_message')
- `args` - Tool arguments as key-value pairs (optional)
**Returns:**
- `MCPToolCallResponse` - Tool execution result
**Example:**
```typescript
const result = await client._callToolByName("slack_send_message", {
channel: "#general",
text: "Hello!",
});
```
### getTool()
Gets a specific tool definition.
```typescript
getTool(name: string): MCPTool | undefined
```
**Parameters:**
- `name` - Tool name
**Returns:**
- `MCPTool` or `undefined` if not found
**Example:**
```typescript
const tool = client.getTool("github_create_issue");
console.log(tool?.inputSchema);
```
### getEnabledTools()
Gets all enabled tools (filtered by integrations).
```typescript
getEnabledTools(): MCPTool[]
```
**Returns:**
- Array of `MCPTool` objects
**Example:**
```typescript
const tools = client.getEnabledTools();
console.log(
"Enabled tools:",
tools.map((t) => t.name)
);
```
### getAvailableTools()
Gets all available tools from the server (unfiltered).
```typescript
getAvailableTools(): MCPTool[]
```
**Returns:**
- Array of `MCPTool` objects
**Example:**
```typescript
const tools = client.getAvailableTools();
console.log(
"All tools:",
tools.map((t) => t.name)
);
```
### getOAuthConfig()
Gets OAuth configuration for a specific integration.
```typescript
getOAuthConfig(integrationId: string): OAuthConfig | undefined
```
**Parameters:**
- `integrationId` - Integration identifier
**Returns:**
- `OAuthConfig` or `undefined` if not found
**Example:**
```typescript
const config = client.getOAuthConfig("github");
console.log("Scopes:", config?.scopes);
```
### getAllOAuthConfigs()
Gets all OAuth configurations.
```typescript
getAllOAuthConfigs(): Map
```
**Returns:**
- Map of integration IDs to OAuth configurations
**Example:**
```typescript
const configs = client.getAllOAuthConfigs();
for (const [integrationId, config] of configs) {
console.log(`${integrationId}: ${config.provider}`);
}
```
### onMessage()
Registers a message handler.
```typescript
onMessage(handler: (message: any) => void): () => void
```
**Parameters:**
- `handler` - Function to handle messages
**Returns:**
- Unsubscribe function
**Example:**
```typescript
const unsubscribe = client.onMessage((message) => {
console.log("Message:", message);
});
// Later...
unsubscribe();
```
### isConnected()
Checks if the client is connected.
```typescript
isConnected(): boolean
```
**Returns:**
- `true` if connected, `false` otherwise
**Example:**
```typescript
if (client.isConnected()) {
console.log("Client is connected");
}
```
### isInitialized()
Checks if the client is initialized.
```typescript
isInitialized(): boolean
```
**Returns:**
- `true` if initialized, `false` otherwise
**Example:**
```typescript
if (client.isInitialized()) {
console.log("Client is initialized");
}
```
### getAuthState()
Gets authentication state for a specific provider.
```typescript
getAuthState(provider: string): { authenticated: boolean; lastError?: AuthenticationError } | undefined
```
**Parameters:**
- `provider` - Provider identifier (e.g., 'github', 'gmail')
**Returns:**
- Authentication state object or `undefined` if provider not found
**Example:**
```typescript
const authState = client.getAuthState("github");
if (authState) {
console.log("Authenticated:", authState.authenticated);
if (authState.lastError) {
console.log("Last error:", authState.lastError.message);
}
}
```
### isProviderAuthenticated()
Checks if a specific provider is authenticated.
```typescript
isProviderAuthenticated(provider: string): boolean
```
**Parameters:**
- `provider` - Provider identifier
**Returns:**
- `true` if authenticated, `false` otherwise
**Example:**
```typescript
if (client.isProviderAuthenticated("github")) {
console.log("GitHub is authenticated");
}
```
### reauthenticate()
Manually triggers re-authentication for a provider.
```typescript
async reauthenticate(provider: string): Promise
```
**Parameters:**
- `provider` - Provider identifier
**Returns:**
- `true` if re-authentication succeeded, `false` otherwise
**Throws:**
- Error if provider not found or no re-auth handler configured
**Example:**
```typescript
try {
const success = await client.reauthenticate("github");
if (success) {
console.log("Re-authentication successful");
}
} catch (error) {
console.error("Re-authentication failed:", error);
}
```
## Server Namespace Methods
The `server` namespace provides access to server-level tools and utilities that don't belong to a specific integration.
### client.server.listAllProviders()
List all providers available on the MCP server.
```typescript
async listAllProviders(): Promise
```
**Returns:**
- `MCPToolCallResponse` - Response containing all available providers
**Example:**
```typescript
const result = await client.server.listAllProviders();
console.log("All providers:", result);
```
### client.server.listToolsByIntegration()
List all tools available for a specific integration.
```typescript
async listToolsByIntegration(params: {
integration: string;
}): Promise
```
**Parameters:**
- `params.integration` (string) - The integration identifier (e.g., "github", "gmail")
**Returns:**
- `MCPToolCallResponse` - Response containing tools for the specified integration
**Example:**
```typescript
// List all GitHub tools
const result = await client.server.listToolsByIntegration({
integration: "github",
});
console.log("GitHub tools:", result);
```
### client.server.listConfiguredIntegrations()
List integrations configured for your application. The behavior depends on how you created your client:
- **Default client** (`import { client } from 'integrate-sdk'`): Fetches from server to get integrations configured via `createMCPServer()`
- **Custom client** (`createMCPClient({ integrations: [...] })`): Returns local config (no server call)
- **Server client** (`createMCPServer`): Returns local config (they ARE the server)
```typescript
async listConfiguredIntegrations(options?: {
includeToolMetadata?: boolean;
}): Promise<{
integrations: ConfiguredIntegration[];
}>
```
**Parameters:**
- `options` (optional) - Configuration options
- `includeToolMetadata` (boolean, default: false) - If true, fetches full tool metadata from the server for all configured integrations. Uses batched requests with concurrency control to avoid rate limiting.
**Returns:**
- Object with `integrations` array containing:
- `id` (string) - Integration identifier
- `name` (string) - Integration display name
- `logoUrl` (string | undefined) - URL to the integration's logo image
- `tools` (readonly string[]) - Array of tool names available for this integration
- `hasOAuth` (boolean) - Whether the integration requires OAuth
- `scopes` (readonly string[] | undefined) - OAuth scopes if applicable
- `provider` (string | undefined) - OAuth provider name if applicable
- `description` (string | undefined) - Short library blurb from the integration or the SDK catalog
- `category` (string | undefined) - Library grouping label (e.g. Productivity, Business) from the integration or the SDK catalog
- `toolMetadata` (ToolMetadata[] | undefined) - Full tool metadata when `includeToolMetadata: true` is passed
**Example (default client - fetches from server):**
```typescript
import { client } from "integrate-sdk";
// Fetches from server to get what's actually configured
const { integrations } = await client.server.listConfiguredIntegrations();
console.log(`Server has ${integrations.length} integrations:`);
integrations.forEach((integration) => {
console.log(`- ${integration.name} (${integration.id})`);
});
```
**Example (custom client - local config):**
```typescript
import { createMCPClient, githubIntegration } from "integrate-sdk";
const customClient = createMCPClient({
integrations: [githubIntegration()],
});
// Returns local config - no server call
const { integrations } = await customClient.server.listConfiguredIntegrations();
// Returns [{ id: 'github', ... }]
```
**Example (with metadata - includes server calls):**
```typescript
// Get configured integrations with full tool metadata
const { integrations } = await client.server.listConfiguredIntegrations({
includeToolMetadata: true,
});
integrations.forEach((integration) => {
console.log(`${integration.name}:`);
integration.toolMetadata?.forEach((tool) => {
console.log(` - ${tool.name}`);
console.log(` ${tool.description}`);
if (tool.inputSchema) {
console.log(` Required: ${tool.inputSchema.required?.join(', ') || 'none'}`);
}
});
});
```
**Note:**
- The default client fetches from the server because it has all integrations pre-configured but only some may be configured on the server with OAuth credentials.
- Custom clients return local config because the developer explicitly chose which integrations to use.
- With `includeToolMetadata: true`, it fetches tool metadata for all integrations using batched requests with concurrency control (3 parallel requests at a time) to avoid rate limiting.
- If metadata fetching fails for an integration, it returns an empty array for that integration's `toolMetadata` rather than failing the entire operation.
## Type Definitions
### MCPTool
### MCPToolCallResponse
### MCPToolCallParams
### OAuthConfig
### MCPIntegration
### ConfiguredIntegration
### ReauthContext
## OAuth Types
### PopupOptions
### OAuthFlowConfig
### AuthStatus
### ProviderTokenData
### OAuthCallbackParams
### OAuth Event Types
#### AuthStartedEvent
#### AuthCompleteEvent
#### AuthErrorEvent
#### AuthLogoutEvent
#### AuthDisconnectEvent
## Built-in Integrations
### githubIntegration()
Creates a GitHub integration.
```typescript
function githubIntegration(config: GitHubIntegrationConfig): MCPIntegration;
```
### gmailIntegration()
Creates a Gmail integration.
```typescript
function gmailIntegration(config: GmailIntegrationConfig): MCPIntegration;
```
### genericOAuthIntegration()
Creates a generic OAuth integration.
```typescript
function genericOAuthIntegration(
config: GenericOAuthIntegrationConfig
): MCPIntegration;
```
### createSimpleIntegration()
Creates a simple integration without OAuth.
```typescript
function createSimpleIntegration(config: {
id: string;
tools: string[];
onInit?: (client: any) => Promise | void;
onAfterConnect?: (client: any) => Promise | void;
onDisconnect?: (client: any) => Promise | void;
}): MCPIntegration;
```
**Parameters:**
- `id` - Integration identifier
- `tools` - Array of tool names to enable
- `onInit` - Optional initialization hook
- `onAfterConnect` - Optional post-connection hook
- `onDisconnect` - Optional disconnect hook
## Vercel AI SDK Integration
### VercelAITool
Tool definition compatible with Vercel AI SDK v5:
### VercelAIToolsOptions
Options for converting MCP tools to Vercel AI SDK format:
### getVercelAITools()
Converts all enabled MCP tools to Vercel AI SDK format.
```typescript
function getVercelAITools(
client: MCPClient,
options?: VercelAIToolsOptions
): Record;
```
**Parameters:**
- `client` - Connected MCP client
- `options` - Optional configuration (see VercelAIToolsOptions above)
**Returns:**
- Object mapping tool names to Vercel AI SDK tools
**Example:**
```typescript
// Client-side
const tools = await getVercelAITools(mcpClient);
// Server-side with provider tokens
const tools = await getVercelAITools(serverClient, {
providerTokens: { github: "ghp_...", gmail: "ya29..." },
});
const result = await generateText({
model: openai("gpt-4"),
prompt: "Create a GitHub issue",
tools,
});
```
### convertMCPToolsToVercelAI()
Alternative name for `getVercelAITools()`.
```typescript
function convertMCPToolsToVercelAI(client: MCPClient): Record;
```
### convertMCPToolToVercelAI()
Converts a single MCP tool to Vercel AI SDK format.
```typescript
function convertMCPToolToVercelAI(tool: MCPTool, client: MCPClient): CoreTool;
```
**Parameters:**
- `tool` - MCP tool definition
- `client` - MCP client for execution
**Returns:**
- Tool in Vercel AI SDK format
**Example:**
```typescript
const tool = client.getTool("github_create_issue");
if (tool) {
const vercelTool = convertMCPToolToVercelAI(tool, client);
}
```
## Constants
### Server URL
```typescript
const MCP_SERVER_URL = "https://mcp.integrate.dev/api/v1/mcp";
```
### Default Timeout
```typescript
const DEFAULT_TIMEOUT = 30000; // 30 seconds
```
## Error Types
The SDK provides specific error classes for different failure scenarios.
### IntegrateSDKError
Base error class for all SDK errors.
```typescript
class IntegrateSDKError extends Error {
name: "IntegrateSDKError";
}
```
### AuthenticationError
Error thrown when authentication fails or tokens are invalid.
```typescript
class AuthenticationError extends IntegrateSDKError {
name: "AuthenticationError";
statusCode?: number; // HTTP status code (usually 401)
provider?: string; // OAuth provider name
}
```
**Example:**
```typescript
import { isAuthError, AuthenticationError } from "integrate-sdk";
try {
await client.github.createIssue({
owner: "user",
repo: "repo",
title: "Bug",
});
} catch (error) {
if (isAuthError(error)) {
console.error(`Auth failed for ${error.provider}: ${error.message}`);
}
}
```
### TokenExpiredError
Error thrown when OAuth tokens have expired.
```typescript
class TokenExpiredError extends AuthenticationError {
name: "TokenExpiredError";
provider?: string; // OAuth provider name
}
```
**Example:**
```typescript
import { isTokenExpiredError } from "integrate-sdk";
try {
await client.github.createIssue({
owner: "user",
repo: "repo",
title: "Bug",
});
} catch (error) {
if (isTokenExpiredError(error)) {
console.error(`Token expired for ${error.provider}`);
// Trigger re-authentication
}
}
```
### AuthorizationError
Error thrown when access is forbidden due to insufficient permissions.
```typescript
class AuthorizationError extends IntegrateSDKError {
name: "AuthorizationError";
statusCode?: number; // HTTP status code (usually 403)
requiredScopes?: string[]; // Missing OAuth scopes
}
```
**Example:**
```typescript
import { isAuthorizationError } from "integrate-sdk";
try {
await client.github.createIssue({
owner: "user",
repo: "repo",
title: "Bug",
});
} catch (error) {
if (isAuthorizationError(error)) {
console.error("Insufficient permissions");
if (error.requiredScopes) {
console.error("Required scopes:", error.requiredScopes);
}
}
}
```
### ConnectionError
Error thrown when a connection to the server fails.
```typescript
class ConnectionError extends IntegrateSDKError {
name: "ConnectionError";
statusCode?: number; // HTTP status code
}
```
### ToolCallError
Error thrown when a tool call fails.
```typescript
class ToolCallError extends IntegrateSDKError {
name: "ToolCallError";
toolName: string; // Name of the tool that failed
originalError?: unknown; // Original error from server
}
```
### Error Helper Functions
Type guard functions for error handling:
```typescript
// Check if error is any authentication error
function isAuthError(error: unknown): error is AuthenticationError;
// Check if error is specifically a token expired error
function isTokenExpiredError(error: unknown): error is TokenExpiredError;
// Check if error is an authorization error
function isAuthorizationError(error: unknown): error is AuthorizationError;
```
**Example:**
```typescript
import {
isAuthError,
isTokenExpiredError,
isAuthorizationError,
} from "integrate-sdk";
try {
await client.github.createIssue({
owner: "user",
repo: "repo",
title: "Bug",
});
} catch (error) {
if (isTokenExpiredError(error)) {
// Handle token expiration
} else if (isAuthError(error)) {
// Handle other auth errors
} else if (isAuthorizationError(error)) {
// Handle permission errors
} else {
// Handle other errors
}
}
```
### parseServerError()
Utility function to parse server errors into appropriate error types.
```typescript
function parseServerError(
error: any,
context?: { toolName?: string; provider?: string }
): IntegrateSDKError;
```
This function is used internally by the SDK but can be useful for custom error handling.
## Triggers
The Trigger API allows you to schedule tool executions for one-time or recurring jobs.
### client.trigger.create()
Create a new scheduled trigger.
```typescript
async create(params: CreateTriggerParams): Promise
```
**Parameters:**
**Returns:**
The created trigger with generated ID and metadata.
**Example:**
```typescript
// One-time trigger
const trigger = await client.trigger.create({
name: "Send Email",
toolName: "gmail_send_email",
toolArguments: { to: "user@example.com", subject: "Hello" },
schedule: { type: "once", runAt: new Date("2024-12-13T22:00:00Z") },
});
// Recurring trigger
const daily = await client.trigger.create({
name: "Daily Report",
toolName: "slack_send_message",
toolArguments: { channel: "#team", text: "Daily report" },
schedule: { type: "cron", expression: "0 9 * * *" },
});
```
### client.trigger.list()
List triggers with optional filters.
```typescript
async list(params?: ListTriggersParams): Promise
```
**Parameters:**
**Returns:**
**Example:**
```typescript
// Get all triggers
const { triggers, total } = await client.trigger.list();
// Get active triggers
const active = await client.trigger.list({ status: "active", limit: 10 });
// Filter by tool name
const emailTriggers = await client.trigger.list({
toolName: "gmail_send_email",
});
```
### client.trigger.get()
Get a specific trigger by ID.
```typescript
async get(triggerId: string): Promise
```
**Parameters:**
- `triggerId` (string) - The trigger ID to retrieve
**Returns:**
The trigger details.
**Example:**
```typescript
const trigger = await client.trigger.get("trig_abc123");
console.log(trigger.status); // 'active'
console.log(trigger.nextRunAt); // '2024-12-13T22:00:00Z'
```
### client.trigger.update()
Update an existing trigger.
```typescript
async update(triggerId: string, params: UpdateTriggerParams): Promise
```
**Parameters:**
- `triggerId` (string) - The trigger ID to update
- `params` (UpdateTriggerParams) - Partial trigger updates
**Returns:**
The updated trigger.
**Example:**
```typescript
// Update schedule
await client.trigger.update("trig_abc123", {
schedule: { type: "cron", expression: "0 10 * * *" },
});
// Update arguments
await client.trigger.update("trig_abc123", {
toolArguments: { channel: "#general" },
});
```
### client.trigger.delete()
Delete a trigger permanently.
```typescript
async delete(triggerId: string): Promise
```
**Parameters:**
- `triggerId` (string) - The trigger ID to delete
**Example:**
```typescript
await client.trigger.delete("trig_abc123");
```
### client.trigger.pause()
Pause a trigger (stop future executions without deleting).
```typescript
async pause(triggerId: string): Promise
```
**Parameters:**
- `triggerId` (string) - The trigger ID to pause
**Returns:**
The updated trigger with status `'paused'`.
**Example:**
```typescript
const paused = await client.trigger.pause("trig_abc123");
console.log(paused.status); // 'paused'
```
### client.trigger.resume()
Resume a paused trigger.
```typescript
async resume(triggerId: string): Promise
```
**Parameters:**
- `triggerId` (string) - The trigger ID to resume
**Returns:**
The updated trigger with status `'active'`.
**Example:**
```typescript
const resumed = await client.trigger.resume("trig_abc123");
console.log(resumed.status); // 'active'
```
### client.trigger.run()
Execute a trigger immediately, bypassing the schedule.
```typescript
async run(triggerId: string): Promise
```
**Parameters:**
- `triggerId` (string) - The trigger ID to execute
**Returns:**
**Example:**
```typescript
const result = await client.trigger.run("trig_abc123");
if (result.success) {
console.log("Success:", result.result);
} else {
console.error("Failed:", result.error);
}
```
### Trigger Type
### TriggerSchedule Type
```typescript
type TriggerSchedule =
| { type: "once"; runAt: string | Date }
| { type: "cron"; expression: string };
```
**One-time schedule:**
```typescript
{ type: 'once', runAt: new Date('2024-12-13T22:00:00Z') }
{ type: 'once', runAt: '2024-12-13T22:00:00Z' }
```
**Recurring schedule (cron):**
```typescript
{ type: 'cron', expression: '0 9 * * *' } // Daily at 9 AM
{ type: 'cron', expression: '0 9 * * 1-5' } // Weekdays at 9 AM
{ type: 'cron', expression: '0 */2 * * *' } // Every 2 hours
```
### TriggerCallbacks
Database storage callbacks for server-side configuration:
**Example:**
```typescript
import { createMCPServer } from "integrate-sdk/server";
export const { client } = createMCPServer({
triggers: {
create: async (trigger, context) => {
return db.trigger.create({ data: trigger });
},
get: async (id, context) => {
return db.trigger.findFirst({ where: { id } });
},
list: async (params, context) => {
const triggers = await db.trigger.findMany({
where: { status: params.status },
take: params.limit,
});
return { triggers, total: triggers.length, hasMore: false };
},
update: async (id, updates, context) => {
return db.trigger.update({ where: { id }, data: updates });
},
delete: async (id, context) => {
await db.trigger.delete({ where: { id } });
},
},
});
```
## Next Steps
- Explore [Advanced Usage](/docs/getting-started/advanced-usage) for patterns and techniques
- See example code in the repository