From 86c7dc08cae4d42e1820b98611efed7ccca75bcc Mon Sep 17 00:00:00 2001 From: Felarof Date: Tue, 12 Aug 2025 17:19:39 -0700 Subject: [PATCH] MCP design MCP design mcp design 4 kavlsi design 3 new design --- docs/2-KLAVIS-MCP-DESIGN.md | 453 +++++ docs/2-klavis-api-reference.md | 1570 ++++++++++++++++++ docs/klavis-MCP-tool-design.md | 312 ++++ docs/klavis_api_documentation.md | 2665 ++++++++++++++++++++++++++++++ 4 files changed, 5000 insertions(+) create mode 100644 docs/2-KLAVIS-MCP-DESIGN.md create mode 100644 docs/2-klavis-api-reference.md create mode 100644 docs/klavis-MCP-tool-design.md create mode 100644 docs/klavis_api_documentation.md diff --git a/docs/2-KLAVIS-MCP-DESIGN.md b/docs/2-KLAVIS-MCP-DESIGN.md new file mode 100644 index 000000000..21f296538 --- /dev/null +++ b/docs/2-KLAVIS-MCP-DESIGN.md @@ -0,0 +1,453 @@ +# Klavis MCP Integration Design + +## 1. What Are We Building? + +We are building an MCP (Model Context Protocol) integration for the Nxtscape browser agent using Klavis as the third-party service provider. This integration will allow users to: + +1. **Connect & Install MCP Servers**: Users can install and connect to various MCP servers (Gmail, YouTube, GitHub, Slack, etc.) through a one-time setup process +2. **Automatic Authentication**: During installation, OAuth authentication is handled automatically for servers that require it +3. **Persistent State**: Klavis maintains server instances and OAuth tokens in the cloud +4. **Seamless Tool Access**: Once installed, the browser agent can automatically discover and use tools from connected MCP servers +5. **Natural Language Commands**: Users can give commands like "check my emails from Gmail" and the agent will automatically use the appropriate MCP server tools + +### Key Features: +- **One-time Setup**: Install and authenticate with MCP servers once +- **Cloud-Managed State**: All server instances and auth tokens managed by Klavis +- **Automatic Discovery**: Browser agent automatically detects installed MCP servers +- **Tool Execution**: Direct tool calls to MCP servers through Klavis API +- **Error Handling**: Robust error handling with re-authentication prompts when needed + +### User Journey: +1. User opens settings and installs Gmail MCP server +2. OAuth popup appears for Gmail authentication (one-time) +3. Later, user tells agent: "Check my emails from Gmail" +4. Agent automatically uses the installed Gmail MCP server +5. Results are returned to the user + +## 2. High-Level Architecture + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ Browser Extension │ +├──────────────────────────────────────────────────────────────────────┤ +│ │ +│ User: "Check my Gmail emails" │ +│ │ │ +│ ▼ │ +│ ┌────────────────────────────────────────────────────────────────┐ │ +│ │ BrowserAgent │ │ +│ │ - Receives user command │ │ +│ │ - Identifies Gmail MCP needed │ │ +│ │ - Invokes MCPTool │ │ +│ └────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌────────────────────────────────────────────────────────────────┐ │ +│ │ MCPTool │ │ +│ │ - Similar to FindElementTool pattern │ │ +│ │ - Actions: getInstalledServers, listTools, executeTool │ │ +│ │ - Returns structured ToolOutput │ │ +│ └────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌────────────────────────────────────────────────────────────────┐ │ +│ │ KlavisAPIManager │ │ +│ │ - Manages user ID (browser-specific) │ │ +│ │ - Server instance lifecycle │ │ +│ │ - OAuth authentication flow │ │ +│ │ - Tool discovery and execution │ │ +│ └────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌────────────────────────────────────────────────────────────────┐ │ +│ │ KlavisAPIClient │ │ +│ │ - REST API communication │ │ +│ │ - Request/response validation with Zod │ │ +│ │ - Error handling and retries │ │ +│ └────────────────────────────────────────────────────────────────┘ │ +│ │ +└────────────────────────────────────────────────────────────────────┘ + │ + ▼ HTTPS REST API + ┌──────────────────────────────────────┐ + │ Klavis Cloud │ + │ ┌────────────────────────────────┐ │ + │ │ User Instances │ │ + │ │ - userId: nxtscape_123456 │ │ + │ │ - Gmail Instance (ID, URL) │ │ + │ │ - YouTube Instance (ID, URL) │ │ + │ │ - OAuth tokens & auth state │ │ + │ └────────────────────────────────┘ │ + │ ┌────────────────────────────────┐ │ + │ │ MCP Server Hosting │ │ + │ │ - gmail-mcp-server.klavis.ai │ │ + │ │ - youtube-mcp-server.klavis │ │ + │ │ - Tool execution endpoints │ │ + │ └────────────────────────────────┘ │ + └──────────────────────────────────────┘ +``` + +### Key Flows: + +#### Installation Flow (Admin - Done via UI): +1. User opens settings/integrations UI +2. User clicks "Install Gmail" +3. UI → KlavisAPIManager.installServer('Gmail') +4. KlavisAPIManager → POST /mcp-server/instance/create +5. If OAuth URL returned → Open OAuth popup +6. User completes OAuth → Klavis stores tokens +7. Server instance created and ready for use + +#### Runtime Flow (Using Installed Servers): +1. User: "Check my Gmail emails" +2. BrowserAgent determines Gmail tool is needed +3. BrowserAgent → MCPTool.execute({ action: 'getUserInstances' }) +4. MCPTool → GET /user/instances (finds Gmail with serverUrl) +5. BrowserAgent → MCPTool.execute({ action: 'listTools', serverUrl: 'gmail-url' }) +6. MCPTool → POST /mcp-server/list-tools +7. BrowserAgent → MCPTool.execute({ action: 'callTool', serverUrl: 'gmail-url', toolName: 'list_emails' }) +8. MCPTool → POST /mcp-server/call-tool +9. Results returned to user + +## 3. High-Level Pseudo Code (Simplified) + +### MCPTool (Following FindElementTool Pattern) + +```typescript +// src/lib/tools/mcp/MCPTool.ts +import { z } from "zod" +import { DynamicStructuredTool } from "@langchain/core/tools" +import { ExecutionContext } from "@/lib/runtime/ExecutionContext" +import { toolSuccess, toolError, type ToolOutput } from "@/lib/tools/Tool.interface" + +// Input schema - only runtime operations +const MCPToolInputSchema = z.object({ + action: z.enum(['getUserInstances', 'listTools', 'callTool']), + serverUrl: z.string().optional(), // For listTools and callTool + toolName: z.string().optional(), // For callTool + toolArgs: z.any().optional() // For callTool +}) + +export class MCPTool { + constructor(private executionContext: ExecutionContext) {} + + async execute(input: MCPToolInput): Promise { + try { + // Get manager and API client + const manager = this.executionContext.getKlavisAPIManager() + const userId = await manager.getUserId() + const client = manager.client // Our custom API client + + switch (input.action) { + case 'getUserInstances': + // Get all installed MCP servers for this user + const instances = await client.getUserInstances(userId, 'Nxtscape') + return toolSuccess(JSON.stringify({ instances })) + + case 'listTools': + // List available tools for a specific server + if (!input.serverUrl) { + return toolError("serverUrl required for listTools") + } + const tools = await client.listTools(input.serverUrl) + return toolSuccess(JSON.stringify({ tools })) + + case 'callTool': + // Execute a tool on an MCP server + if (!input.serverUrl || !input.toolName) { + return toolError("serverUrl and toolName required for callTool") + } + const result = await client.callTool( + input.serverUrl, + input.toolName, + input.toolArgs || {} + ) + if (!result.success) { + return toolError(result.error || 'Tool execution failed') + } + return toolSuccess(JSON.stringify(result.result)) + + default: + return toolError(`Unknown action: ${input.action}`) + } + } catch (error) { + return toolError(`MCP operation failed: ${error instanceof Error ? error.message : 'Unknown error'}`) + } + } +} + +// LangChain wrapper factory function +export function createMCPTool(executionContext: ExecutionContext): DynamicStructuredTool { + const mcpTool = new MCPTool(executionContext) + + return new DynamicStructuredTool({ + name: "mcp_tool", + description: "Interact with MCP servers. Actions: getUserInstances, createInstance, listTools, callTool", + schema: MCPToolInputSchema, + func: async (args): Promise => { + const result = await mcpTool.execute(args) + return JSON.stringify(result) + } + }) +} +``` + +### KlavisAPIManager (With Server Installation) + +```typescript +// src/lib/mcp/KlavisAPIManager.ts +import { KlavisAPIClient, type CreateServerResponse } from './KlavisAPIClient' + +/** + * Manages MCP servers - handles user ID, OAuth, and server installation + */ +export class KlavisAPIManager { + private static instance: KlavisAPIManager | null = null + public readonly client: KlavisAPIClient // Our minimal API client + private userId: string | null = null + + private constructor() { + const apiKey = process.env.KLAVIS_API_KEY + if (!apiKey) { + throw new Error("KLAVIS_API_KEY not configured") + } + this.client = new KlavisAPIClient(apiKey) + } + + static getInstance(): KlavisAPIManager { + if (!KlavisAPIManager.instance) { + KlavisAPIManager.instance = new KlavisAPIManager() + } + return KlavisAPIManager.instance + } + + // Get or create browser-specific user ID + async getUserId(): Promise { + if (this.userId) { + return this.userId + } + + const storage = await chrome.storage.local.get(['nxtscape_user_id']) + if (storage.nxtscape_user_id) { + this.userId = storage.nxtscape_user_id as string + return this.userId + } + + this.userId = `nxtscape_${Date.now()}_${Math.random().toString(36).substr(2, 9)}` + await chrome.storage.local.set({ nxtscape_user_id: this.userId }) + return this.userId + } + + /** + * Install a new MCP server (called from UI, not from MCPTool) + * This is an admin operation done before servers can be used + */ + async installServer(serverName: string): Promise { + const userId = await this.getUserId() + + // Create server instance + const server = await this.client.createServerInstance({ + serverName, + userId, + platformName: 'Nxtscape' + }) + + // Handle OAuth if needed + if (server.oauthUrl) { + await this.handleOAuth(server.oauthUrl) + } + + return server + } + + // Simple OAuth handler + private async handleOAuth(oauthUrl: string): Promise { + const tab = await chrome.tabs.create({ url: oauthUrl, active: true }) + + return new Promise((resolve) => { + const checkInterval = setInterval(async () => { + try { + const updatedTab = await chrome.tabs.get(tab.id!) + if (updatedTab.url?.includes('callback')) { + clearInterval(checkInterval) + await chrome.tabs.remove(tab.id!) + resolve() + } + } catch { + clearInterval(checkInterval) + resolve() // Tab closed = assume success + } + }, 1000) + + setTimeout(() => { + clearInterval(checkInterval) + chrome.tabs.remove(tab.id!).catch(() => {}) + resolve() // Timeout = assume success + }, 5 * 60 * 1000) + }) + } +} +``` + +### KlavisAPIClient (Minimal Custom Client - No Zod) + +Since the TypeScript SDK is missing critical methods like `getUserInstances`, we'll build a minimal API client with just the 3 methods we need for runtime: + +```typescript +// src/lib/mcp/KlavisAPIClient.ts + +// Simple type definitions +export interface UserInstance { + id: string + name: string + description: string | null + tools: Array<{ name: string; description: string }> | null + authNeeded: boolean + isAuthenticated: boolean +} + +export interface CreateServerResponse { + serverUrl: string + instanceId: string + oauthUrl?: string | null +} + +export class KlavisAPIClient { + private baseUrl = 'https://api.klavis.ai' + + constructor(private apiKey: string) {} + + private async request(method: string, path: string, body?: any, query?: Record): Promise { + let url = `${this.baseUrl}${path}` + if (query) { + url += '?' + new URLSearchParams(query).toString() + } + + const response = await fetch(url, { + method, + headers: { + 'Authorization': `Bearer ${this.apiKey}`, + 'Content-Type': 'application/json' + }, + body: body ? JSON.stringify(body) : undefined + }) + + if (!response.ok) { + throw new Error(`Klavis API: ${response.status} ${response.statusText}`) + } + return response.json() + } + + // GET /user/instances + async getUserInstances(userId: string, platformName: string): Promise { + const data = await this.request<{ instances: UserInstance[] }>('GET', '/user/instances', undefined, { + user_id: userId, + platform_name: platformName + }) + return data.instances || [] + } + + // POST /mcp-server/instance/create + async createServerInstance(params: { serverName: string, userId: string, platformName: string }): Promise { + return this.request('POST', '/mcp-server/instance/create', params) + } + + // POST /mcp-server/list-tools + async listTools(serverUrl: string): Promise { + const data = await this.request('POST', '/mcp-server/list-tools', { + serverUrl, + format: 'mcp_native', + connectionType: 'StreamableHttp' + }) + return data.tools || [] + } + + // POST /mcp-server/call-tool + async callTool(serverUrl: string, toolName: string, toolArgs: any): Promise { + return this.request('POST', '/mcp-server/call-tool', { + serverUrl, + toolName, + toolArgs, + connectionType: 'StreamableHttp' + }) + } +} +``` + +### ExecutionContext Integration + +```typescript +// src/lib/runtime/ExecutionContext.ts (additions) +import { KlavisAPIManager } from "@/lib/mcp/KlavisAPIManager" + +export class ExecutionContext { + // ... existing code ... + + /** + * Get KlavisAPIManager singleton + */ + getKlavisAPIManager(): KlavisAPIManager { + return KlavisAPIManager.getInstance() + } +} +``` + +## Summary of Design Decisions + +### Why Custom API Client Instead of SDK + +The Klavis TypeScript SDK is missing critical methods like `getUserInstances` that we need. After evaluating options, we decided to build a minimal custom API client because: + +1. **Missing Critical Methods**: SDK doesn't have `getUserInstances` which is essential +2. **Consistency**: Better to have one pattern than mix SDK + direct API calls +3. **Simplicity**: Only 80 lines of code for the 4 methods we need +4. **Control**: Full TypeScript types with Zod validation + +### Final Architecture + +1. **KlavisAPIClient** (~75 lines - No Zod): + - Simple TypeScript interfaces (no Zod) + - `getUserInstances()` - GET /user/instances + - `createServerInstance()` - POST /mcp-server/instance/create + - `listTools()` - POST /mcp-server/list-tools + - `callTool()` - POST /mcp-server/call-tool + +2. **KlavisAPIManager** (~80 lines): + - Singleton pattern + - User ID management (Chrome storage) + - `installServer()` - Admin operation for server setup + - OAuth handling (Chrome tabs) + - Exposes API client for runtime use + +3. **MCPTool** (~50 lines - Runtime only): + - Only runtime operations (no installation) + - `getUserInstances` - Get installed servers + - `listTools` - List server tools + - `callTool` - Execute server tools + - Returns structured ToolOutput + +### Benefits of This Approach + +- **Minimal Code**: ~200 lines total +- **Clean Separation**: Admin operations (installServer) separate from runtime (MCPTool) +- **No External Dependencies**: No Zod, no SDK - just fetch API +- **Type Safe**: Simple TypeScript interfaces +- **Simple**: Each class has one clear responsibility + +### Key Design Decisions + +1. **No Zod**: Simple TypeScript interfaces instead +2. **No SDK**: Custom minimal client due to missing methods +3. **Separation of Concerns**: + - **Installation**: Via UI → KlavisAPIManager.installServer() + - **Runtime**: Via MCPTool → only uses already installed servers +4. **Clear Boundaries**: MCPTool can't install servers, only use them + +### Dependencies + +Environment variable only: +```bash +KLAVIS_API_KEY=your-api-key +``` + +No npm packages needed! \ No newline at end of file diff --git a/docs/2-klavis-api-reference.md b/docs/2-klavis-api-reference.md new file mode 100644 index 000000000..5fe07e966 --- /dev/null +++ b/docs/2-klavis-api-reference.md @@ -0,0 +1,1570 @@ +----------- WEB PAGE ----------- + +TITLE: Create Server Instance - Klavis AI + +URL: https://docs.klavis.ai/api-reference/mcp-server/create-a-server-instance + +CONTENT: + +Klavis AI home page Search... ⌘ K Ask AI + +Dashboard + +Klavis-AI / klavis 3,940 + +Documentation + +API Reference + +Knowledge Base + +API References + +Introduction + +Manage MCP Server + +POST Create Server Instance + +POST Create Unified MCP Server Instance + +GET Get Server Instance + +DEL Delete Server Instance + +MCP Server Metadata + +GET Get All Servers + +GET Get Tools + +Function Calling with MCP + +POST List Tools + +POST Call Tool + +User + +GET Get User Instances + +DEL Delete User + +White Labeling + +POST Create White Label + +GET Get White Label + +Auth / OAuth + +POST Get OAuth URL + +POST Set Auth Token + +GET Get Authentication Metadata + +DEL Delete Auth data for Server Instance + +GitHub OAuth + +Slack OAuth + +Jira OAuth + +Notion OAuth + +Supabase OAuth + +WordPress OAuth + +Gmail OAuth + +Google Calendar OAuth + +Google Drive OAuth + +Google Docs OAuth + +Google Sheets OAuth + +Airtable OAuth + +Asana OAuth + +Close OAuth + +Confluence OAuth + +Salesforce OAuth + +Linear OAuth + +Linkedin OAuth + +Attio OAuth + +Canva OAuth + +Xero OAuth + +Dropbox OAuth + +QuickBooks OAuth + +Create Server Instance + +cURL + +curl --request POST \ + --url https://api.klavis.ai/mcp-server/instance/create \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "serverName": "Affinity", + "userId": "", + "platformName": "", + "connectionType": "StreamableHttp" +}' 200 422 { + "serverUrl" : "" , + "instanceId" : "" , + "oauthUrl" : "" +} Manage MCP Server + +Create Server Instance + +Creates a URL for a specified MCP server, validating the request with an API key and user details. Returns the existing server URL if it already exists for the user. If OAuth is configured for the server, also returns the base OAuth authorization URL. + +POST / mcp-server / instance / create Try it + +Authorizations + +​ Authorization string header required + +Your Klavis AI API key. + +Body + +application/json ​ serverName enum required + +The name of the target MCP server. Case-insensitive (e.g., 'google calendar', 'GOOGLE_CALENDAR', 'Google Calendar' are all valid). + +Available options: Affinity , Airtable , Asana , Attio , Brave Search , ClickUp , Close , Confluence , Discord , Doc2markdown , Firecrawl Deep Research , Firecrawl Web Search , GitHub , Gmail , Gong , Google Calendar , Google Docs , Google Drive , Google Sheets , HubSpot , Jira , Klavis ReportGen , Linear , LinkedIn , Markdown2doc , Motion , Notion , Plai , Postgres , QuickBooks , Resend , Salesforce , Slack , Supabase , WhatsApp , WordPress , YouTube ​ userId string required + +The identifier for the user requesting the server URL. + +Minimum length: 1 ​ platformName string required + +The name of the platform associated with the user. + +Minimum length: 1 ​ connectionType enum + +The connection type to use for the MCP server. Default is STREAMABLE_HTTP. + +Available options: SSE , StreamableHttp + +Response + +200 application/json + +Successful Response + +​ serverUrl string required + +The full URL for connecting to the MCP server, including the instance ID. + +​ instanceId string required + +The unique identifier for this specific server connection instance. + +​ oauthUrl string | null + +The OAuth authorization URL for the specified server, if OAuth is configured. + +Introduction Create Unified MCP Server Instance github linkedin discord Powered by Mintlify ------------------------------------ + + + + + +|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| + +----------- WEB PAGE ----------- + +TITLE: Get Server Instance - Klavis AI + +URL: https://docs.klavis.ai/api-reference/mcp-server/get-server-instance + +CONTENT: + +Klavis AI home page Search... ⌘ K Ask AI + +Dashboard + +Klavis-AI / klavis 3,940 + +Documentation + +API Reference + +Knowledge Base + +API References + +Introduction + +Manage MCP Server + +POST Create Server Instance + +POST Create Unified MCP Server Instance + +GET Get Server Instance + +DEL Delete Server Instance + +MCP Server Metadata + +GET Get All Servers + +GET Get Tools + +Function Calling with MCP + +POST List Tools + +POST Call Tool + +User + +GET Get User Instances + +DEL Delete User + +White Labeling + +POST Create White Label + +GET Get White Label + +Auth / OAuth + +POST Get OAuth URL + +POST Set Auth Token + +GET Get Authentication Metadata + +DEL Delete Auth data for Server Instance + +GitHub OAuth + +Slack OAuth + +Jira OAuth + +Notion OAuth + +Supabase OAuth + +WordPress OAuth + +Gmail OAuth + +Google Calendar OAuth + +Google Drive OAuth + +Google Docs OAuth + +Google Sheets OAuth + +Airtable OAuth + +Asana OAuth + +Close OAuth + +Confluence OAuth + +Salesforce OAuth + +Linear OAuth + +Linkedin OAuth + +Attio OAuth + +Canva OAuth + +Xero OAuth + +Dropbox OAuth + +QuickBooks OAuth + +Get Server Instance + +cURL + +curl --request GET \ + --url https://api.klavis.ai/mcp-server/instance/get/{instance_id} \ + --header 'Authorization: Bearer ' 200 422 { + "instanceId" : "" , + "authNeeded" : false , + "isAuthenticated" : false , + "serverName" : "" , + "platform" : "" , + "externalUserId" : "" +} Manage MCP Server + +Get Server Instance + +Checks the details of a specific server connection instance using its unique ID and API key, returning server details like authentication status and associated server/platform info. + +GET / mcp-server / instance / get / {instance_id} Try it + +Authorizations + +​ Authorization string header required + +Your Klavis AI API key. + +Path Parameters + +​ instance_id string required + +The ID of the connection instance whose status is being checked. This is returned by the Create API. + +Response + +200 application/json + +Successful Response + +​ instanceId string | null + +The unique identifier of the connection instance. + +​ authNeeded boolean default: false + +Indicates whether authentication is required for this server instance. + +​ isAuthenticated boolean default: false + +Indicates whether the instance is authenticated successfully. + +​ serverName string default: "" + +The name of the MCP server associated with the instance. + +​ platform string default: "" + +The platform associated with the instance. + +​ externalUserId string default: "" + +The user's identifier on the external platform. + +Create Unified MCP Server Instance Delete Server Instance github linkedin discord Powered by Mintlify Get Server Instance - Klavis AI ------------------------------------ + + + + +|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| + +----------- WEB PAGE ----------- + +TITLE: Delete Server Instance - Klavis AI + +URL: https://docs.klavis.ai/api-reference/mcp-server/delete-a-server-instance + +CONTENT: + +Klavis AI home page Search... ⌘ K Ask AI + +Dashboard + +Klavis-AI / klavis 3,940 + +Documentation + +API Reference + +Knowledge Base + +API References + +Introduction + +Manage MCP Server + +POST Create Server Instance + +POST Create Unified MCP Server Instance + +GET Get Server Instance + +DEL Delete Server Instance + +MCP Server Metadata + +GET Get All Servers + +GET Get Tools + +Function Calling with MCP + +POST List Tools + +POST Call Tool + +User + +GET Get User Instances + +DEL Delete User + +White Labeling + +POST Create White Label + +GET Get White Label + +Auth / OAuth + +POST Get OAuth URL + +POST Set Auth Token + +GET Get Authentication Metadata + +DEL Delete Auth data for Server Instance + +GitHub OAuth + +Slack OAuth + +Jira OAuth + +Notion OAuth + +Supabase OAuth + +WordPress OAuth + +Gmail OAuth + +Google Calendar OAuth + +Google Drive OAuth + +Google Docs OAuth + +Google Sheets OAuth + +Airtable OAuth + +Asana OAuth + +Close OAuth + +Confluence OAuth + +Salesforce OAuth + +Linear OAuth + +Linkedin OAuth + +Attio OAuth + +Canva OAuth + +Xero OAuth + +Dropbox OAuth + +QuickBooks OAuth + +Delete Server Instance + +cURL + +curl --request DELETE \ + --url https://api.klavis.ai/mcp-server/instance/delete/{instance_id} \ + --header 'Authorization: Bearer ' 200 422 { + "success" : true , + "message" : "" +} Manage MCP Server + +Delete Server Instance + +Completely removes a server connection instance using its unique ID, deleting all associated data from the system. + +DELETE / mcp-server / instance / delete / {instance_id} Try it + +Authorizations + +​ Authorization string header required + +Your Klavis AI API key. + +Path Parameters + +​ instance_id string required + +The ID of the connection instance to delete. + +Response + +200 application/json + +Successful Response + +​ success boolean required ​ message string | null Get Server Instance Get All Servers github linkedin discord Powered by Mintlify Delete Server Instance - Klavis AI ------------------------------------ + +|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| +----------- WEB PAGE ----------- + +TITLE: Get All Servers - Klavis AI + +URL: https://docs.klavis.ai/api-reference/mcp-server/get-all-servers + +CONTENT: + +Klavis AI home page Search... ⌘ K Ask AI + +Dashboard + +Klavis-AI / klavis 3,940 + +Documentation + +API Reference + +Knowledge Base + +API References + +Introduction + +Manage MCP Server + +POST Create Server Instance + +POST Create Unified MCP Server Instance + +GET Get Server Instance + +DEL Delete Server Instance + +MCP Server Metadata + +GET Get All Servers + +GET Get Tools + +Function Calling with MCP + +POST List Tools + +POST Call Tool + +User + +GET Get User Instances + +DEL Delete User + +White Labeling + +POST Create White Label + +GET Get White Label + +Auth / OAuth + +POST Get OAuth URL + +POST Set Auth Token + +GET Get Authentication Metadata + +DEL Delete Auth data for Server Instance + +GitHub OAuth + +Slack OAuth + +Jira OAuth + +Notion OAuth + +Supabase OAuth + +WordPress OAuth + +Gmail OAuth + +Google Calendar OAuth + +Google Drive OAuth + +Google Docs OAuth + +Google Sheets OAuth + +Airtable OAuth + +Asana OAuth + +Close OAuth + +Confluence OAuth + +Salesforce OAuth + +Linear OAuth + +Linkedin OAuth + +Attio OAuth + +Canva OAuth + +Xero OAuth + +Dropbox OAuth + +QuickBooks OAuth + +Get All Servers + +cURL + +curl --request GET \ + --url https://api.klavis.ai/mcp-server/servers \ + --header 'Authorization: Bearer ' 200 { + "servers" : [ + { + "id" : "3c90c3cc-0d44-4b50-8888-8dd25736052a" , + "name" : "" , + "description" : "" , + "tools" : [ + { + "name" : "" , + "description" : "" + } + ], + "authNeeded" : true + } + ] +} MCP Server Metadata + +Get All Servers + +Get all MCP servers with their basic information including id, name, description, and tools. + +GET / mcp-server / servers Try it + +Authorizations + +​ Authorization string header required + +Your Klavis AI API key. + +Response + +200 - application/json + +Successful Response + +​ servers McpServer · object[] required + +Show child attributes + +Delete Server Instance Get Tools github linkedin discord Powered by Mintlify Get All Servers - Klavis AI ------------------------------------ + +|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| +----------- WEB PAGE ----------- + +TITLE: Get Tools - Klavis AI + +URL: https://docs.klavis.ai/api-reference/mcp-server/get-tools + +CONTENT: + +Klavis AI home page Search... ⌘ K Ask AI + +Dashboard + +Klavis-AI / klavis 3,940 + +Documentation + +API Reference + +Knowledge Base + +API References + +Introduction + +Manage MCP Server + +POST Create Server Instance + +POST Create Unified MCP Server Instance + +GET Get Server Instance + +DEL Delete Server Instance + +MCP Server Metadata + +GET Get All Servers + +GET Get Tools + +Function Calling with MCP + +POST List Tools + +POST Call Tool + +User + +GET Get User Instances + +DEL Delete User + +White Labeling + +POST Create White Label + +GET Get White Label + +Auth / OAuth + +POST Get OAuth URL + +POST Set Auth Token + +GET Get Authentication Metadata + +DEL Delete Auth data for Server Instance + +GitHub OAuth + +Slack OAuth + +Jira OAuth + +Notion OAuth + +Supabase OAuth + +WordPress OAuth + +Gmail OAuth + +Google Calendar OAuth + +Google Drive OAuth + +Google Docs OAuth + +Google Sheets OAuth + +Airtable OAuth + +Asana OAuth + +Close OAuth + +Confluence OAuth + +Salesforce OAuth + +Linear OAuth + +Linkedin OAuth + +Attio OAuth + +Canva OAuth + +Xero OAuth + +Dropbox OAuth + +QuickBooks OAuth + +Get Tools + +cURL + +curl --request GET \ + --url https://api.klavis.ai/mcp-server/tools/{server_name} \ + --header 'Authorization: Bearer ' 200 422 { + "tools" : [ + { + "name" : "" , + "description" : "" + } + ] +} MCP Server Metadata + +Get Tools + +Get list of tool names for a specific MCP server. Mainly used for querying metadata about the MCP server. + +GET / mcp-server / tools / {server_name} Try it + +Authorizations + +​ Authorization string header required + +Your Klavis AI API key. + +Path Parameters + +​ server_name enum required + +The name of the target MCP server. Case-insensitive (e.g., 'google calendar', 'GOOGLE_CALENDAR', 'Google Calendar' are all valid). + +Available options: Affinity , Airtable , Asana , Attio , Brave Search , ClickUp , Close , Confluence , Discord , Doc2markdown , Firecrawl Deep Research , Firecrawl Web Search , GitHub , Gmail , Gong , Google Calendar , Google Docs , Google Drive , Google Sheets , HubSpot , Jira , Klavis ReportGen , Linear , LinkedIn , Markdown2doc , Motion , Notion , Plai , Postgres , QuickBooks , Resend , Salesforce , Slack , Supabase , WhatsApp , WordPress , YouTube + +Response + +200 application/json + +Successful Response + +​ tools ServerTool · object[] + +List of available tools with their descriptions + +Show child attributes + +Get All Servers List Tools github linkedin discord Powered by Mintlify Get Tools - Klavis AI ------------------------------------ + +|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| + +----------- WEB PAGE ----------- + +TITLE: List Tools - Klavis AI + +URL: https://docs.klavis.ai/api-reference/mcp-server/list-tools + +CONTENT: + +Klavis AI home page Search... ⌘ K Ask AI + +Dashboard + +Klavis-AI / klavis 3,940 + +Documentation + +API Reference + +Knowledge Base + +API References + +Introduction + +Manage MCP Server + +POST Create Server Instance + +POST Create Unified MCP Server Instance + +GET Get Server Instance + +DEL Delete Server Instance + +MCP Server Metadata + +GET Get All Servers + +GET Get Tools + +Function Calling with MCP + +POST List Tools + +POST Call Tool + +User + +GET Get User Instances + +DEL Delete User + +White Labeling + +POST Create White Label + +GET Get White Label + +Auth / OAuth + +POST Get OAuth URL + +POST Set Auth Token + +GET Get Authentication Metadata + +DEL Delete Auth data for Server Instance + +GitHub OAuth + +Slack OAuth + +Jira OAuth + +Notion OAuth + +Supabase OAuth + +WordPress OAuth + +Gmail OAuth + +Google Calendar OAuth + +Google Drive OAuth + +Google Docs OAuth + +Google Sheets OAuth + +Airtable OAuth + +Asana OAuth + +Close OAuth + +Confluence OAuth + +Salesforce OAuth + +Linear OAuth + +Linkedin OAuth + +Attio OAuth + +Canva OAuth + +Xero OAuth + +Dropbox OAuth + +QuickBooks OAuth + +List Tools + +cURL + +curl --request POST \ + --url https://api.klavis.ai/mcp-server/list-tools \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "serverUrl": "", + "connectionType": "StreamableHttp", + "format": "mcp_native" +}' 200 422 { + "success" : true , + "tools" : [ + "" + ], + "format" : "openai" , + "error" : "" +} Function Calling with MCP + +List Tools + +Lists all tools available for a specific remote MCP server in various AI model formats. + +This eliminates the need for manual MCP code implementation and format conversion. Under the hood, Klavis instantiates an MCP client and establishes a connection with the remote MCP server to retrieve available tools. + +POST / mcp-server / list-tools Try it + +Authorizations + +​ Authorization string header required + +Your Klavis AI API key. + +Body + +application/json ​ serverUrl string required + +The full URL for connecting to the MCP server + +​ connectionType enum + +The connection type to use for the MCP server. Default is STREAMABLE_HTTP. + +Available options: SSE , StreamableHttp ​ format enum + +The format to return tools in. Default is MCP Native format for maximum compatibility. + +Available options: openai , anthropic , gemini , mcp_native + +Response + +200 application/json + +Successful Response + +​ success boolean required + +Whether the list tools request was successful + +​ format enum required + +The format of the returned tools + +Available options: openai , anthropic , gemini , mcp_native ​ tools any[] | null + +List of tools in the requested format + +​ error string | null + +Error message, if the request failed + +Get Tools Call Tool github linkedin discord Powered by Mintlify List Tools - Klavis AI ------------------------------------ + +|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| +----------- WEB PAGE ----------- + +TITLE: Call Tool - Klavis AI + +URL: https://docs.klavis.ai/api-reference/mcp-server/call-tool + +CONTENT: + +Klavis AI home page Search... ⌘ K Ask AI + +Dashboard + +Klavis-AI / klavis 3,940 + +Documentation + +API Reference + +Knowledge Base + +API References + +Introduction + +Manage MCP Server + +POST Create Server Instance + +POST Create Unified MCP Server Instance + +GET Get Server Instance + +DEL Delete Server Instance + +MCP Server Metadata + +GET Get All Servers + +GET Get Tools + +Function Calling with MCP + +POST List Tools + +POST Call Tool + +User + +GET Get User Instances + +DEL Delete User + +White Labeling + +POST Create White Label + +GET Get White Label + +Auth / OAuth + +POST Get OAuth URL + +POST Set Auth Token + +GET Get Authentication Metadata + +DEL Delete Auth data for Server Instance + +GitHub OAuth + +Slack OAuth + +Jira OAuth + +Notion OAuth + +Supabase OAuth + +WordPress OAuth + +Gmail OAuth + +Google Calendar OAuth + +Google Drive OAuth + +Google Docs OAuth + +Google Sheets OAuth + +Airtable OAuth + +Asana OAuth + +Close OAuth + +Confluence OAuth + +Salesforce OAuth + +Linear OAuth + +Linkedin OAuth + +Attio OAuth + +Canva OAuth + +Xero OAuth + +Dropbox OAuth + +QuickBooks OAuth + +Call Tool + +cURL + +curl --request POST \ + --url https://api.klavis.ai/mcp-server/call-tool \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "serverUrl": "", + "toolName": "", + "toolArgs": {}, + "connectionType": "StreamableHttp" +}' 200 422 { + "success" : true , + "result" : { + "content" : [ + "" + ], + "isError" : false + }, + "error" : "" +} Function Calling with MCP + +Call Tool + +Calls a tool on a specific remote MCP server, used for function calling. Eliminates the need for manual MCP code implementation. Under the hood, Klavis will instantiates an MCP client and establishes a connection with the remote MCP server to call the tool. + +POST / mcp-server / call-tool Try it + +Authorizations + +​ Authorization string header required + +Your Klavis AI API key. + +Body + +application/json ​ serverUrl string required + +The full URL for connecting to the MCP server + +​ toolName string required + +The name of the tool to call + +​ toolArgs object + +The input parameters for the tool + +​ connectionType enum + +The connection type to use for the MCP server. Default is STREAMABLE_HTTP. + +Available options: SSE , StreamableHttp + +Response + +200 application/json + +Successful Response + +​ success boolean required + +Whether the API call was successful + +​ result object | null + +The result of the tool call, if successful +The server's response to a tool call. + +Show child attributes + +​ error string | null + +Error message, if the tool call failed + +List Tools Get User Instances github linkedin discord Powered by Mintlify Call Tool - Klavis AI ------------------------------------ + +|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| +----------- WEB PAGE ----------- + +TITLE: Get User Instances - Klavis AI + +URL: https://docs.klavis.ai/api-reference/user/get-user-instances + +CONTENT: + +Klavis AI home page Search... ⌘ K Ask AI + +Dashboard + +Klavis-AI / klavis 3,940 + +Documentation + +API Reference + +Knowledge Base + +API References + +Introduction + +Manage MCP Server + +POST Create Server Instance + +POST Create Unified MCP Server Instance + +GET Get Server Instance + +DEL Delete Server Instance + +MCP Server Metadata + +GET Get All Servers + +GET Get Tools + +Function Calling with MCP + +POST List Tools + +POST Call Tool + +User + +GET Get User Instances + +DEL Delete User + +White Labeling + +POST Create White Label + +GET Get White Label + +Auth / OAuth + +POST Get OAuth URL + +POST Set Auth Token + +GET Get Authentication Metadata + +DEL Delete Auth data for Server Instance + +GitHub OAuth + +Slack OAuth + +Jira OAuth + +Notion OAuth + +Supabase OAuth + +WordPress OAuth + +Gmail OAuth + +Google Calendar OAuth + +Google Drive OAuth + +Google Docs OAuth + +Google Sheets OAuth + +Airtable OAuth + +Asana OAuth + +Close OAuth + +Confluence OAuth + +Salesforce OAuth + +Linear OAuth + +Linkedin OAuth + +Attio OAuth + +Canva OAuth + +Xero OAuth + +Dropbox OAuth + +QuickBooks OAuth + +Get User Instances + +cURL + +curl --request GET \ + --url https://api.klavis.ai/user/instances \ + --header 'Authorization: Bearer ' 200 422 { + "instances" : [ + { + "id" : "3c90c3cc-0d44-4b50-8888-8dd25736052a" , + "name" : "" , + "description" : "" , + "tools" : [ + { + "name" : "" , + "description" : "" + } + ], + "authNeeded" : true , + "isAuthenticated" : false + } + ] +} User + +Get User Instances + +Get all MCP server instances information by user ID and platform name. + +GET / user / instances Try it + +Authorizations + +​ Authorization string header required + +Your Klavis AI API key. + +Query Parameters + +​ user_id string required + +The external user ID + +​ platform_name string required + +The platform name + +Response + +200 application/json + +Successful Response + +​ instances ExtendedMcpServer · object[] required + +Show child attributes + +Call Tool Delete User github linkedin discord Powered by Mintlify Get User Instances - Klavis AI ------------------------------------ + +|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| + +----------- WEB PAGE ----------- + +TITLE: Delete User - Klavis AI + +URL: https://docs.klavis.ai/api-reference/user/delete-user + +CONTENT: + +Klavis AI home page Search... ⌘ K Ask AI + +Dashboard + +Klavis-AI / klavis 3,940 + +Documentation + +API Reference + +Knowledge Base + +API References + +Introduction + +Manage MCP Server + +POST Create Server Instance + +POST Create Unified MCP Server Instance + +GET Get Server Instance + +DEL Delete Server Instance + +MCP Server Metadata + +GET Get All Servers + +GET Get Tools + +Function Calling with MCP + +POST List Tools + +POST Call Tool + +User + +GET Get User Instances + +DEL Delete User + +White Labeling + +POST Create White Label + +GET Get White Label + +Auth / OAuth + +POST Get OAuth URL + +POST Set Auth Token + +GET Get Authentication Metadata + +DEL Delete Auth data for Server Instance + +GitHub OAuth + +Slack OAuth + +Jira OAuth + +Notion OAuth + +Supabase OAuth + +WordPress OAuth + +Gmail OAuth + +Google Calendar OAuth + +Google Drive OAuth + +Google Docs OAuth + +Google Sheets OAuth + +Airtable OAuth + +Asana OAuth + +Close OAuth + +Confluence OAuth + +Salesforce OAuth + +Linear OAuth + +Linkedin OAuth + +Attio OAuth + +Canva OAuth + +Xero OAuth + +Dropbox OAuth + +QuickBooks OAuth + +Delete User + +cURL + +curl --request DELETE \ + --url https://api.klavis.ai/user/delete/{user_id} \ + --header 'Authorization: Bearer ' 200 422 { + "success" : true , + "message" : "" +} User + +Delete User + +Delete a user and all associated data by user_id. Users cannot delete their own accounts. This operation will permanently remove all user data. + +DELETE / user / delete / {user_id} Try it + +Authorizations + +​ Authorization string header required + +Your Klavis AI API key. + +Path Parameters + +​ user_id string required + +The identifier for the user to delete. + +Minimum length: 1 + +Response + +200 application/json + +Successful Response + +​ success boolean required ​ message string required Get User Instances Create White Label github linkedin discord Powered by Mintlify Delete User - Klavis AI ------------------------------------ + + + + + + diff --git a/docs/klavis-MCP-tool-design.md b/docs/klavis-MCP-tool-design.md new file mode 100644 index 000000000..92e4f30ca --- /dev/null +++ b/docs/klavis-MCP-tool-design.md @@ -0,0 +1,312 @@ +# Klavis MCP (Model Context Protocol) Integration Design + +## Table of Contents +1. [Overview](#overview) +2. [Architecture](#architecture) +3. [API Integration](#api-integration) +4. [Core Components](#core-components) +5. [Authentication Strategy](#authentication-strategy) +6. [Tool Discovery](#tool-discovery) +7. [Implementation Plan](#implementation-plan) +8. [Usage Examples](#usage-examples) +9. [Error Handling](#error-handling) +10. [Future Considerations](#future-considerations) + +## Overview + +This document outlines the design for integrating Klavis MCP (Model Context Protocol) servers into the Nxtscape Chrome extension using the Klavis REST API. The integration allows our AI agents to interact with external services like YouTube, Gmail, GitHub, etc., through a unified interface. All MCP-related components will be organized under the `src/lib/tools/mcp/` directory to maintain consistency with the existing tool structure. + +### Goals +- **API-First Approach**: Use Klavis REST API directly instead of SDK +- **Cloud-Managed State**: Leverage Klavis cloud for all server state management +- **User Isolation**: Support multiple users with browser-specific IDs +- **Seamless Integration**: MCP tools should work like native Nxtscape tools +- **Type Safety**: Full TypeScript support with Zod validation +- **Progressive Enhancement**: Start simple, add complexity incrementally + +### Non-Goals +- Building our own MCP server implementation +- Caching server instances locally +- Modifying the core agent architecture +- Creating UI for MCP server management (initially) + +## Architecture + +### High-Level Architecture + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ Chrome Extension Context │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────┐ ┌──────────────────┐ ┌──────────────┐ │ +│ │ ProductivityAgent │ ──▶│ ToolRegistry │ ──▶│ YouTubeTool │ │ +│ └─────────────────┘ └──────────────────┘ └──────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌─────────────────────────────────────────┐│ +│ │ NxtscapeTool (Base Class) ││ +│ │ - Standard tool interface ││ +│ │ - Built-in LLM access ││ +│ └─────────────────────────────────────────┘│ +│ │ │ +│ ▼ │ +│ ┌─────────────────────────────────────────────────────────────────┐│ +│ │ MCPToolManager (Singleton) ││ +│ │ - User ID management (browser-specific) ││ +│ │ - API client for Klavis REST endpoints ││ +│ │ - OAuth flow handling ││ +│ │ - Tool execution proxy ││ +│ │ - No local caching (state in Klavis cloud) ││ +│ └─────────────────────────────────────────────────────────────────┘│ +│ │ │ +│ ▼ │ +│ ┌─────────────────────────────────────────────────────────────────┐│ +│ │ Chrome Storage API ││ +│ │ - Store browser-specific user ID only ││ +│ │ - No server instance caching ││ +│ └─────────────────────────────────────────────────────────────────┘│ +│ │ +└───────────────────────────────────│─────────────────────────────────┘ + │ + ▼ + ┌───────────────────────┐ + │ Klavis REST API │ + │ - Create MCP servers │ + │ - Get user instances│ + │ - List tools │ + │ - Execute tools │ + │ - Manage auth state │ + └───────────────────────┘ +``` + +### Data Flow + +1. **User Request**: "Summarize this YouTube video: [URL]" +2. **Agent Selection**: ProductivityAgent identifies YouTubeTool as appropriate +3. **Tool Execution**: YouTubeTool.execute() called with action and params +4. **User ID**: MCPToolManager retrieves/creates browser-specific user ID +5. **Server Lookup**: GET /user/instances to find existing servers for user +6. **Server Creation**: If no server exists, POST /mcp-server/instance/create +7. **Authentication**: If oauthUrl returned, immediately handle OAuth flow +8. **Tool Discovery**: POST /mcp-server/list-tools to get available tools +9. **Tool Execution**: POST /mcp-server/call-tool to execute the tool +10. **Response**: Formatted result returned to user + +## API Integration + +### Klavis REST API Overview + +**Base URL**: `https://api.klavis.ai` + +**Authentication**: Bearer token using API key +```typescript +headers: { + 'Authorization': `Bearer ${apiKey}`, + 'Content-Type': 'application/json' +} +``` + +### Key API Endpoints + +#### 1. User Instance Management +```typescript +// Get all server instances for a user +GET /user/instances +// Returns: Array of server instances with serverUrl, instanceId, serverType, etc. +``` + +#### 2. Server Instance Operations +```typescript +// Create new server instance +POST /mcp-server/instance/create +{ + serverName: Klavis.McpServerName, // e.g., 'youtube', 'gmail' + userId: string, // Browser-specific user ID + platformName: "Nxtscape" +} +// Returns: { serverUrl, instanceId, oauthUrl? } + +// Get specific instance +GET /mcp-server/instance/get/{instance_id} + +// Delete instance +DELETE /mcp-server/instance/delete/{instance_id} +``` + +#### 3. Tool Operations +```typescript +// List available tools for a server +POST /mcp-server/list-tools +{ + serverUrl: string, + format: "openai" | "anthropic" | "gemini" | "mcp_native" +} + +// Execute a tool +POST /mcp-server/call-tool +{ + serverUrl: string, + toolName: string, + toolArgs: object, + connectionType: "StreamableHttp" | "SSE" +} +``` + +### User Management Strategy + +Each browser instance gets a unique user ID stored in Chrome local storage: + +```typescript +// Generate/retrieve user ID +async function getUserId(): Promise { + const storage = await chrome.storage.local.get(['nxtscape_user_id']); + if (storage.nxtscape_user_id) { + return storage.nxtscape_user_id; + } + + const userId = `nxtscape_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`; + await chrome.storage.local.set({ nxtscape_user_id: userId }); + return userId; +} +``` + +### API Client Implementation + +```typescript +class KlavisAPIClient { + private baseUrl = 'https://api.klavis.ai'; + private apiKey: string; + + constructor(apiKey: string) { + this.apiKey = apiKey; + } + + private async request( + method: string, + path: string, + body?: any + ): Promise { + const response = await fetch(`${this.baseUrl}${path}`, { + method, + headers: { + 'Authorization': `Bearer ${this.apiKey}`, + 'Content-Type': 'application/json' + }, + body: body ? JSON.stringify(body) : undefined + }); + + if (!response.ok) { + throw new Error(`Klavis API error: ${response.statusText}`); + } + + return response.json(); + } + + // API methods + async getUserInstances(userId: string) { + return this.request('GET', `/user/instances`); + } + + async createServerInstance(params: CreateServerParams) { + return this.request('POST', '/mcp-server/instance/create', params); + } + + async listTools(serverUrl: string) { + return this.request('POST', '/mcp-server/list-tools', { + serverUrl, + format: 'openai' + }); + } + + async callTool(params: CallToolParams) { + return this.request('POST', '/mcp-server/call-tool', { + ...params, + connectionType: 'StreamableHttp' + }); + } +} +``` + +## API Key Management + +### Configuration Strategy + +The Klavis API key is managed through environment variables and injected at build time: + +```javascript +// webpack.config.js +new webpack.DefinePlugin({ + 'process.env.KLAVIS_API_KEY': JSON.stringify(process.env.KLAVIS_API_KEY), + // Other environment variables... +}) +``` + +### Usage Pattern + +```typescript +// In tool implementations +const apiKey = process.env.KLAVIS_API_KEY +if (!apiKey) { + console.warn('⚠️ KLAVIS_API_KEY not found, MCP tools will be unavailable') + return [] +} + +const klavisClient = new KlavisClient({ apiKey }) +``` + +### Development Setup + +1. Create a `.env` file in the project root: +```bash +KLAVIS_API_KEY=your_api_key_here +``` + +2. The webpack build process will inject this at compile time +3. MCP tools gracefully degrade when the key is missing + +## Core Components + +### 1. MCPToolManager (Singleton Service) + +**Purpose**: Centralized service for managing MCP server instances using Klavis REST API. All server state is managed in Klavis cloud. + +```typescript +// Location: src/lib/tools/mcp/MCPToolManager.ts + +class MCPToolManager { + private static instance: MCPToolManager + private apiClient: KlavisAPIClient | null = null + + // Singleton pattern + static getInstance(): MCPToolManager + + // User management + async getUserId(): Promise + + // Server management (no local caching) + async getUserServers(userId: string): Promise + async getOrCreateServer(userId: string, serverType: string): Promise + async createServer(userId: string, serverType: string): Promise + + // Tool operations + async listServerTools(serverUrl: string): Promise + async executeServerTool(serverUrl: string, toolName: string, toolArgs: any): Promise + + // OAuth handling + async handleOAuthAuthentication(serverInstance: ServerInstance): Promise + private async waitForOAuthCompletion(tabId: number): Promise + + // Utility methods + private getServerName(serverType: string): string + private initializeClient(): KlavisAPIClient +} +``` + +**Key Responsibilities**: +- Manages browser-specific user IDs +- Communicates with Klavis REST API +- Handles OAuth authentication flows +- No local caching - all state in Klavis cloud +- Executes tools via Klavis API +loud infrastructure for all state management. diff --git a/docs/klavis_api_documentation.md b/docs/klavis_api_documentation.md new file mode 100644 index 000000000..e176711ea --- /dev/null +++ b/docs/klavis_api_documentation.md @@ -0,0 +1,2665 @@ +# + +[Klavis AI home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)](https://www.klavis.ai/) + +Search... + +Ctrl KAsk AI + +Search... + +Navigation + +Gmail OAuth + +Authorize Gmail + +Authorize Gmail + +cURL + +Copy + +Ask AI + +``` +curl --request GET \ + --url https://api.klavis.ai/oauth/gmail/authorize +``` + +200 + +422 + +Copy + +Ask AI + +``` +"" +``` + +GET + +/ + +oauth + +/ + +gmail + +/ + +authorize + +Try it + +Authorize Gmail + +cURL + +Copy + +Ask AI + +``` +curl --request GET \ + --url https://api.klavis.ai/oauth/gmail/authorize +``` + +200 + +422 + +Copy + +Ask AI + +``` +"" +``` + +Assistant + +Responses are generated using AI and may contain mistakes. + +#### Query Parameters + +[​](https://docs.klavis.ai/api-reference/gmail-oauth/authorize-gmail#parameter-instance-id) + +instance\_id + +string + +required + +Unique identifier for the client instance requesting authorization + +[​](https://docs.klavis.ai/api-reference/gmail-oauth/authorize-gmail#parameter-client-id) + +client\_id + +string \| null + +Client ID for white labeling, if not provided will use default credentials + +[​](https://docs.klavis.ai/api-reference/gmail-oauth/authorize-gmail#parameter-scope) + +scope + +string \| null + +Optional OAuth scopes to request (comma-separated string) + +[​](https://docs.klavis.ai/api-reference/gmail-oauth/authorize-gmail#parameter-redirect-url) + +redirect\_url + +string \| null + +Optional URL to redirect to after authorization completes + +#### Response + +200 + +200422 + +application/json + +Successful Response + +The response is of type `any`. + +[Authorize Wordpress](https://docs.klavis.ai/api-reference/wordpress-oauth/authorize-wordpress) [Authorize Gcalendar](https://docs.klavis.ai/api-reference/google-calendar-oauth/authorize-google-calendar) + +------------------------------ + +# + +[Klavis AI home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)](https://www.klavis.ai/) + +Search... + +Ctrl KAsk AI + +Search... + +Navigation + +API References + +Introduction + +On this page + +- [Base URL](https://docs.klavis.ai/api-reference/introduction#base-url) +- [Authentication](https://docs.klavis.ai/api-reference/introduction#authentication) +- [Response codes](https://docs.klavis.ai/api-reference/introduction#response-codes) +- [Rate limit](https://docs.klavis.ai/api-reference/introduction#rate-limit) + +## [​](https://docs.klavis.ai/api-reference/introduction\#base-url) Base URL + +The Klavis API is built on REST principles. We enforce HTTPS in every request to improve data security, integrity, and privacy. The API does not support HTTP. + +All requests contain the following base URL: + +Copy + +Ask AI + +``` +https://api.klavis.ai + +``` + +## [​](https://docs.klavis.ai/api-reference/introduction\#authentication) Authentication + +To authenticate you need to add an Authorization header with the contents of the header being Bearer key\_123456789 where key\_123456789 is your API Key. + +Copy + +Ask AI + +``` +Authorization: Bearer key_123456789 + +``` + +## [​](https://docs.klavis.ai/api-reference/introduction\#response-codes) Response codes + +Klavis uses standard HTTP codes to indicate the success or failure of your requests. + +In general, 2xx HTTP codes correspond to success, 4xx codes are for user-related failures, and 5xx codes are for infrastructure issues. + +| Status | Description | +| --- | --- | +| 200 | Successful request. | +| 400 | Check that the parameters were correct. | +| 401 | The API key used was missing. | +| 403 | The API key used was invalid. | +| 404 | The resource was not found. | +| 429 | The rate limit was exceeded. | +| 5xx | Indicates an error with Klavis servers. | + +Check Error Codes for a comprehensive breakdown of all possible API errors. + +## [​](https://docs.klavis.ai/api-reference/introduction\#rate-limit) Rate limit + +The default maximum rate limit is 2 requests per second. This number can be increased for trusted senders by request. After that, you’ll hit the rate limit and receive a 429 response error code. + +Assistant + +Responses are generated using AI and may contain mistakes. + +[Create a Server Instance](https://docs.klavis.ai/api-reference/mcp-server/create-a-server-instance) + +------------------------------ + +# + +[Klavis AI home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)](https://www.klavis.ai/) + +Search... + +Ctrl KAsk AI + +Search... + +Navigation + +Function Calling with MCP + +Call Tool + +Call Tool + +cURL + +Copy + +Ask AI + +``` +curl --request POST \ + --url https://api.klavis.ai/mcp-server/call-tool \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "serverUrl": "", + "toolName": "", + "toolArgs": {}, + "connectionType": "StreamableHttp" +}' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "success": true, + "result": { + "content": [\ + ""\ + ], + "isError": false + }, + "error": "" +} +``` + +POST + +/ + +mcp-server + +/ + +call-tool + +Try it + +Call Tool + +cURL + +Copy + +Ask AI + +``` +curl --request POST \ + --url https://api.klavis.ai/mcp-server/call-tool \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "serverUrl": "", + "toolName": "", + "toolArgs": {}, + "connectionType": "StreamableHttp" +}' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "success": true, + "result": { + "content": [\ + ""\ + ], + "isError": false + }, + "error": "" +} +``` + +Assistant + +Responses are generated using AI and may contain mistakes. + +#### Authorizations + +[​](https://docs.klavis.ai/api-reference/mcp-server/call-tool#authorization-authorization) + +Authorization + +string + +header + +required + +Your Klavis AI API key. + +#### Body + +application/json + +[​](https://docs.klavis.ai/api-reference/mcp-server/call-tool#body-server-url) + +serverUrl + +string + +required + +The full URL for connecting to the MCP server + +[​](https://docs.klavis.ai/api-reference/mcp-server/call-tool#body-tool-name) + +toolName + +string + +required + +The name of the tool to call + +[​](https://docs.klavis.ai/api-reference/mcp-server/call-tool#body-tool-args) + +toolArgs + +object + +The input parameters for the tool + +[​](https://docs.klavis.ai/api-reference/mcp-server/call-tool#body-connection-type) + +connectionType + +enum + +The connection type to use for the MCP server. Default is STREAMABLE\_HTTP. + +Available options: + +`SSE`, + +`StreamableHttp` + +#### Response + +200 + +200422 + +application/json + +Successful Response + +[​](https://docs.klavis.ai/api-reference/mcp-server/call-tool#response-success) + +success + +boolean + +required + +Whether the API call was successful + +[​](https://docs.klavis.ai/api-reference/mcp-server/call-tool#response-result) + +result + +object \| null + +The result of the tool call, if successful +The server's response to a tool call. + +Show child attributes + +[​](https://docs.klavis.ai/api-reference/mcp-server/call-tool#response-result-content) + +result.content + +any\[\] + +required + +The content of the tool call + +[​](https://docs.klavis.ai/api-reference/mcp-server/call-tool#response-result-is-error) + +result.isError + +boolean + +default:false + +Whether the tool call was successful + +[​](https://docs.klavis.ai/api-reference/mcp-server/call-tool#response-error) + +error + +string \| null + +Error message, if the tool call failed + +[List Tools](https://docs.klavis.ai/api-reference/mcp-server/list-tools) [Get user instances](https://docs.klavis.ai/api-reference/user/get-server-instances) + +------------------------------ + +# + +[Klavis AI home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)](https://www.klavis.ai/) + +Search... + +Ctrl KAsk AI + +Search... + +Navigation + +Manage MCP Server + +Create a Server Instance + +Create a Server Instance + +cURL + +Copy + +Ask AI + +``` +curl --request POST \ + --url https://api.klavis.ai/mcp-server/instance/create \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "serverName": "Affinity", + "userId": "", + "platformName": "", + "connectionType": "StreamableHttp" +}' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "serverUrl": "", + "instanceId": "", + "oauthUrl": "" +} +``` + +POST + +/ + +mcp-server + +/ + +instance + +/ + +create + +Try it + +Create a Server Instance + +cURL + +Copy + +Ask AI + +``` +curl --request POST \ + --url https://api.klavis.ai/mcp-server/instance/create \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "serverName": "Affinity", + "userId": "", + "platformName": "", + "connectionType": "StreamableHttp" +}' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "serverUrl": "", + "instanceId": "", + "oauthUrl": "" +} +``` + +Assistant + +Responses are generated using AI and may contain mistakes. + +#### Authorizations + +[​](https://docs.klavis.ai/api-reference/mcp-server/create-a-server-instance#authorization-authorization) + +Authorization + +string + +header + +required + +Your Klavis AI API key. + +#### Body + +application/json + +[​](https://docs.klavis.ai/api-reference/mcp-server/create-a-server-instance#body-server-name) + +serverName + +enum + +required + +The name of the target MCP server. + +Available options: + +`Affinity`, + +`Airtable`, + +`Asana`, + +`Attio`, + +`ClickUp`, + +`Close`, + +`Confluence`, + +`Discord`, + +`Doc2markdown`, + +`Firecrawl Deep Research`, + +`Firecrawl Web Search`, + +`GitHub`, + +`Gmail`, + +`Gong`, + +`Google Calendar`, + +`Google Docs`, + +`Google Drive`, + +`Google Sheets`, + +`HubSpot`, + +`Jira`, + +`Klavis ReportGen`, + +`Linear`, + +`Markdown2doc`, + +`Notion`, + +`Plai`, + +`Postgres`, + +`Resend`, + +`Salesforce`, + +`Slack`, + +`Supabase`, + +`WhatsApp`, + +`WordPress`, + +`YouTube` + +[​](https://docs.klavis.ai/api-reference/mcp-server/create-a-server-instance#body-user-id) + +userId + +string + +required + +The identifier for the user requesting the server URL. + +Minimum length: `1` + +[​](https://docs.klavis.ai/api-reference/mcp-server/create-a-server-instance#body-platform-name) + +platformName + +string + +required + +The name of the platform associated with the user. + +Minimum length: `1` + +[​](https://docs.klavis.ai/api-reference/mcp-server/create-a-server-instance#body-connection-type) + +connectionType + +enum + +The connection type to use for the MCP server. Default is STREAMABLE\_HTTP. + +Available options: + +`SSE`, + +`StreamableHttp` + +#### Response + +200 + +200422 + +application/json + +Successful Response + +[​](https://docs.klavis.ai/api-reference/mcp-server/create-a-server-instance#response-server-url) + +serverUrl + +string + +required + +The full URL for connecting to the MCP server, including the instance ID. + +[​](https://docs.klavis.ai/api-reference/mcp-server/create-a-server-instance#response-instance-id) + +instanceId + +string + +required + +The unique identifier for this specific server connection instance. + +[​](https://docs.klavis.ai/api-reference/mcp-server/create-a-server-instance#response-oauth-url) + +oauthUrl + +string \| null + +The OAuth authorization URL for the specified server, if OAuth is configured. + +[Introduction](https://docs.klavis.ai/api-reference/introduction) [Get Server Instance](https://docs.klavis.ai/api-reference/mcp-server/get-server-instance) + +------------------------------ + +# + +[Klavis AI home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)](https://www.klavis.ai/) + +Search... + +Ctrl KAsk AI + +Search... + +Navigation + +Manage MCP Server + +Delete a Server Instance + +Delete a Server Instance + +cURL + +Copy + +Ask AI + +``` +curl --request DELETE \ + --url https://api.klavis.ai/mcp-server/instance/delete/{instance_id} \ + --header 'Authorization: Bearer ' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "success": true, + "message": "" +} +``` + +DELETE + +/ + +mcp-server + +/ + +instance + +/ + +delete + +/ + +{instance\_id} + +Try it + +Delete a Server Instance + +cURL + +Copy + +Ask AI + +``` +curl --request DELETE \ + --url https://api.klavis.ai/mcp-server/instance/delete/{instance_id} \ + --header 'Authorization: Bearer ' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "success": true, + "message": "" +} +``` + +Assistant + +Responses are generated using AI and may contain mistakes. + +#### Authorizations + +[​](https://docs.klavis.ai/api-reference/mcp-server/delete-a-server-instance#authorization-authorization) + +Authorization + +string + +header + +required + +Your Klavis AI API key. + +#### Path Parameters + +[​](https://docs.klavis.ai/api-reference/mcp-server/delete-a-server-instance#parameter-instance-id) + +instance\_id + +string + +required + +The ID of the connection instance to delete. + +#### Response + +200 + +200422 + +application/json + +Successful Response + +[​](https://docs.klavis.ai/api-reference/mcp-server/delete-a-server-instance#response-success) + +success + +boolean + +required + +[​](https://docs.klavis.ai/api-reference/mcp-server/delete-a-server-instance#response-message) + +message + +string \| null + +[Get Server Instance](https://docs.klavis.ai/api-reference/mcp-server/get-server-instance) [Get All Servers](https://docs.klavis.ai/api-reference/mcp-server/get-all-servers) + +------------------------------ + +# + +[Klavis AI home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)](https://www.klavis.ai/) + +Search... + +Ctrl KAsk AI + +Search... + +Navigation + +Auth / OAuth + +Delete Auth data for a Server Instance + +Delete Auth data for a Server Instance + +cURL + +Copy + +Ask AI + +``` +curl --request DELETE \ + --url https://api.klavis.ai/mcp-server/instance/delete-auth/{instance_id} \ + --header 'Authorization: Bearer ' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "success": true, + "message": "" +} +``` + +DELETE + +/ + +mcp-server + +/ + +instance + +/ + +delete-auth + +/ + +{instance\_id} + +Try it + +Delete Auth data for a Server Instance + +cURL + +Copy + +Ask AI + +``` +curl --request DELETE \ + --url https://api.klavis.ai/mcp-server/instance/delete-auth/{instance_id} \ + --header 'Authorization: Bearer ' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "success": true, + "message": "" +} +``` + +Assistant + +Responses are generated using AI and may contain mistakes. + +#### Authorizations + +[​](https://docs.klavis.ai/api-reference/mcp-server/delete-auth-data-for-a-server-instance#authorization-authorization) + +Authorization + +string + +header + +required + +Your Klavis AI API key. + +#### Path Parameters + +[​](https://docs.klavis.ai/api-reference/mcp-server/delete-auth-data-for-a-server-instance#parameter-instance-id) + +instance\_id + +string + +required + +The ID of the connection instance to delete auth for. + +#### Response + +200 + +200422 + +application/json + +Successful Response + +[​](https://docs.klavis.ai/api-reference/mcp-server/delete-auth-data-for-a-server-instance#response-success) + +success + +boolean + +required + +[​](https://docs.klavis.ai/api-reference/mcp-server/delete-auth-data-for-a-server-instance#response-message) + +message + +string \| null + +[Get Authentication Metadata](https://docs.klavis.ai/api-reference/mcp-server/get-auth-metadata) [Authorize Github](https://docs.klavis.ai/api-reference/github-oauth/authorize-github) + +------------------------------ + +# + +[Klavis AI home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)](https://www.klavis.ai/) + +Search... + +Ctrl KAsk AI + +Search... + +Navigation + +MCP Server Metadata + +Get All Servers + +Get All Servers + +cURL + +Copy + +Ask AI + +``` +curl --request GET \ + --url https://api.klavis.ai/mcp-server/servers \ + --header 'Authorization: Bearer ' +``` + +200 + +Copy + +Ask AI + +``` +{ + "servers": [\ + {\ + "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",\ + "name": "",\ + "description": "",\ + "tools": [\ + {\ + "name": "",\ + "description": ""\ + }\ + ],\ + "authNeeded": true\ + }\ + ] +} +``` + +GET + +/ + +mcp-server + +/ + +servers + +Try it + +Get All Servers + +cURL + +Copy + +Ask AI + +``` +curl --request GET \ + --url https://api.klavis.ai/mcp-server/servers \ + --header 'Authorization: Bearer ' +``` + +200 + +Copy + +Ask AI + +``` +{ + "servers": [\ + {\ + "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",\ + "name": "",\ + "description": "",\ + "tools": [\ + {\ + "name": "",\ + "description": ""\ + }\ + ],\ + "authNeeded": true\ + }\ + ] +} +``` + +Assistant + +Responses are generated using AI and may contain mistakes. + +#### Authorizations + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-all-servers#authorization-authorization) + +Authorization + +string + +header + +required + +Your Klavis AI API key. + +#### Response + +200 - application/json + +Successful Response + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-all-servers#response-servers) + +servers + +McpServer · object\[\] + +required + +Show child attributes + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-all-servers#response-servers-id) + +id + +string + +required + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-all-servers#response-servers-name) + +name + +string + +required + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-all-servers#response-servers-description) + +description + +string \| null + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-all-servers#response-servers-tools) + +tools + +ServerTool · object\[\] \| null + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-all-servers#response-servers-auth-needed) + +authNeeded + +boolean + +default:true + +[Delete a Server Instance](https://docs.klavis.ai/api-reference/mcp-server/delete-a-server-instance) [Get Tools](https://docs.klavis.ai/api-reference/mcp-server/get-tools) + +------------------------------ + +# + +[Klavis AI home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)](https://www.klavis.ai/) + +Search... + +Ctrl KAsk AI + +Search... + +Navigation + +Auth / OAuth + +Get Authentication Metadata + +Get Authentication Metadata + +cURL + +Copy + +Ask AI + +``` +curl --request GET \ + --url https://api.klavis.ai/mcp-server/instance/get-auth/{instance_id} \ + --header 'Authorization: Bearer ' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "success": true, + "authData": {}, + "error": "" +} +``` + +GET + +/ + +mcp-server + +/ + +instance + +/ + +get-auth + +/ + +{instance\_id} + +Try it + +Get Authentication Metadata + +cURL + +Copy + +Ask AI + +``` +curl --request GET \ + --url https://api.klavis.ai/mcp-server/instance/get-auth/{instance_id} \ + --header 'Authorization: Bearer ' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "success": true, + "authData": {}, + "error": "" +} +``` + +Assistant + +Responses are generated using AI and may contain mistakes. + +#### Authorizations + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-auth-metadata#authorization-authorization) + +Authorization + +string + +header + +required + +Your Klavis AI API key. + +#### Path Parameters + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-auth-metadata#parameter-instance-id) + +instance\_id + +string + +required + +The ID of the connection instance to get auth metadata for. + +#### Response + +200 + +200422 + +application/json + +Successful Response + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-auth-metadata#response-success) + +success + +boolean + +required + +Whether the request was successful + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-auth-metadata#response-auth-data) + +authData + +object \| null + +Complete authentication metadata including access token, refresh token, scope, expiration, and platform-specific data + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-auth-metadata#response-error) + +error + +string \| null + +Error message if the request failed + +[Set Auth Token](https://docs.klavis.ai/api-reference/mcp-server/set-auth-token) [Delete Auth data for a Server Instance](https://docs.klavis.ai/api-reference/mcp-server/delete-auth-data-for-a-server-instance) + +------------------------------ + +# + +[Klavis AI home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)](https://www.klavis.ai/) + +Search... + +Ctrl KAsk AI + +Search... + +Navigation + +Auth / OAuth + +Get OAuth URL + +Get OAuth URL + +cURL + +Copy + +Ask AI + +``` +curl --request POST \ + --url https://api.klavis.ai/mcp-server/oauth-url \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "serverName": "Affinity", + "instanceId": "", + "clientId": "", + "scope": "", + "redirectUrl": "" +}' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "oauthUrl": "" +} +``` + +POST + +/ + +mcp-server + +/ + +oauth-url + +Try it + +Get OAuth URL + +cURL + +Copy + +Ask AI + +``` +curl --request POST \ + --url https://api.klavis.ai/mcp-server/oauth-url \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "serverName": "Affinity", + "instanceId": "", + "clientId": "", + "scope": "", + "redirectUrl": "" +}' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "oauthUrl": "" +} +``` + +Assistant + +Responses are generated using AI and may contain mistakes. + +#### Authorizations + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-oauth-url#authorization-authorization) + +Authorization + +string + +header + +required + +Your Klavis AI API key. + +#### Body + +application/json + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-oauth-url#body-server-name) + +serverName + +enum + +required + +The name of the target MCP server. + +Available options: + +`Affinity`, + +`Airtable`, + +`Asana`, + +`Attio`, + +`ClickUp`, + +`Close`, + +`Confluence`, + +`Discord`, + +`Doc2markdown`, + +`Firecrawl Deep Research`, + +`Firecrawl Web Search`, + +`GitHub`, + +`Gmail`, + +`Gong`, + +`Google Calendar`, + +`Google Docs`, + +`Google Drive`, + +`Google Sheets`, + +`HubSpot`, + +`Jira`, + +`Klavis ReportGen`, + +`Linear`, + +`Markdown2doc`, + +`Notion`, + +`Plai`, + +`Postgres`, + +`Resend`, + +`Salesforce`, + +`Slack`, + +`Supabase`, + +`WhatsApp`, + +`WordPress`, + +`YouTube` + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-oauth-url#body-instance-id) + +instanceId + +string + +required + +The unique identifier for the connection instance. + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-oauth-url#body-client-id) + +clientId + +string \| null + +Optional client ID for white labeling. If not provided, will use default credentials. + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-oauth-url#body-scope) + +scope + +string \| null + +Optional OAuth scopes to request (comma-separated string). + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-oauth-url#body-redirect-url) + +redirectUrl + +string \| null + +Optional URL to redirect to after authorization completes. + +#### Response + +200 + +200422 + +application/json + +Successful Response + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-oauth-url#response-oauth-url) + +oauthUrl + +string + +required + +The OAuth authorization URL for the specified server. + +[Get](https://docs.klavis.ai/api-reference/white-labeling/get) [Set Auth Token](https://docs.klavis.ai/api-reference/mcp-server/set-auth-token) + +------------------------------ + +# + +[Klavis AI home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)](https://www.klavis.ai/) + +Search... + +Ctrl KAsk AI + +Search... + +Navigation + +Manage MCP Server + +Get Server Instance + +Get Server Instance + +cURL + +Copy + +Ask AI + +``` +curl --request GET \ + --url https://api.klavis.ai/mcp-server/instance/get/{instance_id} \ + --header 'Authorization: Bearer ' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "instanceId": "", + "authNeeded": false, + "isAuthenticated": false, + "serverName": "", + "platform": "", + "externalUserId": "" +} +``` + +GET + +/ + +mcp-server + +/ + +instance + +/ + +get + +/ + +{instance\_id} + +Try it + +Get Server Instance + +cURL + +Copy + +Ask AI + +``` +curl --request GET \ + --url https://api.klavis.ai/mcp-server/instance/get/{instance_id} \ + --header 'Authorization: Bearer ' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "instanceId": "", + "authNeeded": false, + "isAuthenticated": false, + "serverName": "", + "platform": "", + "externalUserId": "" +} +``` + +Assistant + +Responses are generated using AI and may contain mistakes. + +#### Authorizations + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-server-instance#authorization-authorization) + +Authorization + +string + +header + +required + +Your Klavis AI API key. + +#### Path Parameters + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-server-instance#parameter-instance-id) + +instance\_id + +string + +required + +The ID of the connection instance whose status is being checked. This is returned by the Create API. + +#### Response + +200 + +200422 + +application/json + +Successful Response + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-server-instance#response-instance-id) + +instanceId + +string \| null + +The unique identifier of the connection instance. + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-server-instance#response-auth-needed) + +authNeeded + +boolean + +default:false + +Indicates whether authentication is required for this server instance. + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-server-instance#response-is-authenticated) + +isAuthenticated + +boolean + +default:false + +Indicates whether the instance is authenticated successfully. + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-server-instance#response-server-name) + +serverName + +string + +default:"" + +The name of the MCP server associated with the instance. + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-server-instance#response-platform) + +platform + +string + +default:"" + +The platform associated with the instance. + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-server-instance#response-external-user-id) + +externalUserId + +string + +default:"" + +The user's identifier on the external platform. + +[Create a Server Instance](https://docs.klavis.ai/api-reference/mcp-server/create-a-server-instance) [Delete a Server Instance](https://docs.klavis.ai/api-reference/mcp-server/delete-a-server-instance) + +------------------------------ + +# + +[Klavis AI home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)](https://www.klavis.ai/) + +Search... + +Ctrl KAsk AI + +Search... + +Navigation + +MCP Server Metadata + +Get Tools + +Get Tools + +cURL + +Copy + +Ask AI + +``` +curl --request GET \ + --url https://api.klavis.ai/mcp-server/tools/{server_name} \ + --header 'Authorization: Bearer ' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "tools": [\ + {\ + "name": "",\ + "description": ""\ + }\ + ] +} +``` + +GET + +/ + +mcp-server + +/ + +tools + +/ + +{server\_name} + +Try it + +Get Tools + +cURL + +Copy + +Ask AI + +``` +curl --request GET \ + --url https://api.klavis.ai/mcp-server/tools/{server_name} \ + --header 'Authorization: Bearer ' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "tools": [\ + {\ + "name": "",\ + "description": ""\ + }\ + ] +} +``` + +Assistant + +Responses are generated using AI and may contain mistakes. + +#### Authorizations + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-tools#authorization-authorization) + +Authorization + +string + +header + +required + +Your Klavis AI API key. + +#### Path Parameters + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-tools#parameter-server-name) + +server\_name + +enum + +required + +The name of the target MCP server. + +Available options: + +`Affinity`, + +`Airtable`, + +`Asana`, + +`Attio`, + +`ClickUp`, + +`Close`, + +`Confluence`, + +`Discord`, + +`Doc2markdown`, + +`Firecrawl Deep Research`, + +`Firecrawl Web Search`, + +`GitHub`, + +`Gmail`, + +`Gong`, + +`Google Calendar`, + +`Google Docs`, + +`Google Drive`, + +`Google Sheets`, + +`HubSpot`, + +`Jira`, + +`Klavis ReportGen`, + +`Linear`, + +`Markdown2doc`, + +`Notion`, + +`Plai`, + +`Postgres`, + +`Resend`, + +`Salesforce`, + +`Slack`, + +`Supabase`, + +`WhatsApp`, + +`WordPress`, + +`YouTube` + +#### Response + +200 + +200422 + +application/json + +Successful Response + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-tools#response-tools) + +tools + +ServerTool · object\[\] + +List of available tools with their descriptions + +Show child attributes + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-tools#response-tools-name) + +name + +string + +required + +[​](https://docs.klavis.ai/api-reference/mcp-server/get-tools#response-tools-description) + +description + +string + +required + +[Get All Servers](https://docs.klavis.ai/api-reference/mcp-server/get-all-servers) [List Tools](https://docs.klavis.ai/api-reference/mcp-server/list-tools) + +------------------------------ + +# + +[Klavis AI home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)](https://www.klavis.ai/) + +Search... + +Ctrl KAsk AI + +Search... + +Navigation + +Function Calling with MCP + +List Tools + +List Tools + +cURL + +Copy + +Ask AI + +``` +curl --request POST \ + --url https://api.klavis.ai/mcp-server/list-tools \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "serverUrl": "", + "connectionType": "StreamableHttp", + "format": "mcp_native" +}' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "success": true, + "tools": [\ + ""\ + ], + "format": "openai", + "error": "" +} +``` + +POST + +/ + +mcp-server + +/ + +list-tools + +Try it + +List Tools + +cURL + +Copy + +Ask AI + +``` +curl --request POST \ + --url https://api.klavis.ai/mcp-server/list-tools \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "serverUrl": "", + "connectionType": "StreamableHttp", + "format": "mcp_native" +}' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "success": true, + "tools": [\ + ""\ + ], + "format": "openai", + "error": "" +} +``` + +Assistant + +Responses are generated using AI and may contain mistakes. + +#### Authorizations + +[​](https://docs.klavis.ai/api-reference/mcp-server/list-tools#authorization-authorization) + +Authorization + +string + +header + +required + +Your Klavis AI API key. + +#### Body + +application/json + +[​](https://docs.klavis.ai/api-reference/mcp-server/list-tools#body-server-url) + +serverUrl + +string + +required + +The full URL for connecting to the MCP server + +[​](https://docs.klavis.ai/api-reference/mcp-server/list-tools#body-connection-type) + +connectionType + +enum + +The connection type to use for the MCP server. Default is STREAMABLE\_HTTP. + +Available options: + +`SSE`, + +`StreamableHttp` + +[​](https://docs.klavis.ai/api-reference/mcp-server/list-tools#body-format) + +format + +enum + +The format to return tools in. Default is MCP Native format for maximum compatibility. + +Available options: + +`openai`, + +`anthropic`, + +`gemini`, + +`mcp_native` + +#### Response + +200 + +200422 + +application/json + +Successful Response + +[​](https://docs.klavis.ai/api-reference/mcp-server/list-tools#response-success) + +success + +boolean + +required + +Whether the list tools request was successful + +[​](https://docs.klavis.ai/api-reference/mcp-server/list-tools#response-format) + +format + +enum + +required + +The format of the returned tools + +Available options: + +`openai`, + +`anthropic`, + +`gemini`, + +`mcp_native` + +[​](https://docs.klavis.ai/api-reference/mcp-server/list-tools#response-tools) + +tools + +any\[\] \| null + +List of tools in the requested format + +[​](https://docs.klavis.ai/api-reference/mcp-server/list-tools#response-error) + +error + +string \| null + +Error message, if the request failed + +[Get Tools](https://docs.klavis.ai/api-reference/mcp-server/get-tools) [Call Tool](https://docs.klavis.ai/api-reference/mcp-server/call-tool) + +------------------------------ + +# + +[Klavis AI home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)](https://www.klavis.ai/) + +Search... + +Ctrl KAsk AI + +Search... + +Navigation + +Auth / OAuth + +Set Auth Token + +Set Auth Token + +cURL + +Copy + +Ask AI + +``` +curl --request POST \ + --url https://api.klavis.ai/mcp-server/instance/set-auth-token \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "instanceId": "", + "authToken": "" +}' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "success": true, + "message": "" +} +``` + +POST + +/ + +mcp-server + +/ + +instance + +/ + +set-auth-token + +Try it + +Set Auth Token + +cURL + +Copy + +Ask AI + +``` +curl --request POST \ + --url https://api.klavis.ai/mcp-server/instance/set-auth-token \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "instanceId": "", + "authToken": "" +}' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "success": true, + "message": "" +} +``` + +Assistant + +Responses are generated using AI and may contain mistakes. + +#### Authorizations + +[​](https://docs.klavis.ai/api-reference/mcp-server/set-auth-token#authorization-authorization) + +Authorization + +string + +header + +required + +Your Klavis AI API key. + +#### Body + +application/json + +[​](https://docs.klavis.ai/api-reference/mcp-server/set-auth-token#body-instance-id) + +instanceId + +string + +required + +The unique identifier for the connection instance + +[​](https://docs.klavis.ai/api-reference/mcp-server/set-auth-token#body-auth-token) + +authToken + +string + +required + +The authentication token to save + +#### Response + +200 + +200422 + +application/json + +Successful Response + +[​](https://docs.klavis.ai/api-reference/mcp-server/set-auth-token#response-success) + +success + +boolean + +required + +[​](https://docs.klavis.ai/api-reference/mcp-server/set-auth-token#response-message) + +message + +string \| null + +[Get OAuth URL](https://docs.klavis.ai/api-reference/mcp-server/get-oauth-url) [Get Authentication Metadata](https://docs.klavis.ai/api-reference/mcp-server/get-auth-metadata) + +------------------------------ + +# + +[Klavis AI home page![light logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)![dark logo](https://mintlify.s3.us-west-1.amazonaws.com/klavisai/images/logo/light.png)](https://www.klavis.ai/) + +Search... + +Ctrl KAsk AI + +Search... + +Navigation + +User + +Get user instances + +Get user instances + +cURL + +Copy + +Ask AI + +``` +curl --request GET \ + --url https://api.klavis.ai/user/instances \ + --header 'Authorization: Bearer ' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "instances": [\ + {\ + "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",\ + "name": "",\ + "description": "",\ + "tools": [\ + {\ + "name": "",\ + "description": ""\ + }\ + ],\ + "authNeeded": true,\ + "isAuthenticated": false\ + }\ + ] +} +``` + +GET + +/ + +user + +/ + +instances + +Try it + +Get user instances + +cURL + +Copy + +Ask AI + +``` +curl --request GET \ + --url https://api.klavis.ai/user/instances \ + --header 'Authorization: Bearer ' +``` + +200 + +422 + +Copy + +Ask AI + +``` +{ + "instances": [\ + {\ + "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",\ + "name": "",\ + "description": "",\ + "tools": [\ + {\ + "name": "",\ + "description": ""\ + }\ + ],\ + "authNeeded": true,\ + "isAuthenticated": false\ + }\ + ] +} +``` + +Assistant + +Responses are generated using AI and may contain mistakes. + +#### Authorizations + +[​](https://docs.klavis.ai/api-reference/user/get-server-instances#authorization-authorization) + +Authorization + +string + +header + +required + +Your Klavis AI API key. + +#### Query Parameters + +[​](https://docs.klavis.ai/api-reference/user/get-server-instances#parameter-user-id) + +user\_id + +string + +required + +The external user ID + +[​](https://docs.klavis.ai/api-reference/user/get-server-instances#parameter-platform-name) + +platform\_name + +string + +required + +The platform name + +#### Response + +200 + +200422 + +application/json + +Successful Response + +[​](https://docs.klavis.ai/api-reference/user/get-server-instances#response-instances) + +instances + +ExtendedMcpServer · object\[\] + +required + +Show child attributes + +[Call Tool](https://docs.klavis.ai/api-reference/mcp-server/call-tool) [Create](https://docs.klavis.ai/api-reference/white-labeling/create) \ No newline at end of file