Skip to content

LLM.md

Latest commit

 

History

History
272 lines (213 loc) · 7.65 KB

LLM.md

File metadata and controls

272 lines (213 loc) · 7.65 KB

Klavis AI - LLM API Documentation

Overview

Klavis AI is an open-source MCP (Model Context Protocol) integration platform that that let AI agents use any tools reliably at any scale.

Key Features:

  • Instant Integration with Python/TypeScript SDKs or REST API
  • Built-in OAuth flows and API key management
  • 100+ tools across CRM, GSuite, dev tools, sales, search, etc.
  • Multi-platform LLM provider support (OpenAI, Anthropic, Gemini, etc.)
  • Strata: One MCP server for AI agents to use tools progressively at any scale

Installation

REST API

Base URL: https://api.klavis.ai
Authentication: Bearer token (API key in Authorization header)

Create Strata Server

curl -X POST https://api.klavis.ai/mcp-server/strata/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "servers": ["GitHub", "Linear"]
  }'

Response:

{
  "strataServerUrl": "https://strata.klavis.ai/mcp/?strata_id=...",
  "strataId": "strata_abc123",
  "addedServers": ["GitHub", "Linear"],
  "oauthUrls": {
    "GitHub": "https://api.klavis.ai/oauth/github/authorize?instance_id=...",
    "Linear": "https://api.klavis.ai/oauth/linear/authorize?instance_id=..."
  }
}

Add Servers to Strata

curl -X POST https://api.klavis.ai/mcp-server/strata/add \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "strataId": "strata_abc123",
    "servers": ["Slack", "Notion"]
  }'

Get Available Servers

curl -X GET https://api.klavis.ai/mcp-server/servers \
  -H "Authorization: Bearer YOUR_API_KEY"

Python SDK

pip install klavis

TypeScript/JavaScript SDK

npm install klavis

API Key Setup

Sign up at klavis.ai and create your API key.

Quick Start

Python SDK

from klavis import Klavis
from klavis.types import McpServerName, ToolFormat

# Initialize client
klavis_client = Klavis(api_key="your_api_key")

# Create Strata MCP server (aggregates multiple MCP servers)
response = klavis_client.mcp_server.create_strata_server(
    servers=[McpServerName.GITHUB, McpServerName.LINEAR],
    user_id="user_123"
)

# Handle OAuth if needed
if response.oauth_urls:
    for server_name, oauth_url in response.oauth_urls.items():
        print(f"Authorize {server_name}: {oauth_url}")

TypeScript SDK

import { Klavis } from 'klavis';

const klavisClient = new Klavis({ apiKey: 'your_api_key' });

// Create Strata MCP server
const response = await klavisClient.mcpServer.createStrataServer({
    servers: [Klavis.McpServerName.Github, Klavis.McpServerName.Linear],
    userId: "user_123"
});

Use Case - OpenAI Integration

import json
from openai import OpenAI
from klavis import Klavis
from klavis.types import McpServerName, ToolFormat

openai_client = OpenAI(api_key="openai_key")
klavis_client = Klavis(api_key="klavis_key")

# Create Strata server with multiple services
response = klavis_client.mcp_server.create_strata_server(
    servers=[McpServerName.GMAIL, McpServerName.SLACK],
    user_id="user_123"
)

# Handle OAuth authorization for each service
if response.oauth_urls:
    for server_name, oauth_url in response.oauth_urls.items():
        print(f"Please open this URL to complete {server_name} OAuth authorization: {oauth_url}")

def openai_with_mcp_server(mcp_server_url: str, user_query: str):
    messages = [
        {"role": "system", "content": "You are a helpful assistant. Use the available tools to answer the user's question."},
        {"role": "user", "content": user_query}
    ]
    
    tools_info = klavis_client.mcp_server.list_tools(
        server_url=mcp_server_url,
        format=ToolFormat.OPENAI
    )
    
    max_iterations = 20 
    iteration = 0
    
    while iteration < max_iterations:
        iteration += 1
        
        response = openai_client.chat.completions.create(
            model="gpt-4o-mini",
            messages=messages,
            tools=tools_info.tools,
            tool_choice="auto",
        )
        
        assistant_message = response.choices[0].message
        
        if assistant_message.tool_calls:
            messages.append({
                "role": "assistant",
                "content": assistant_message.content,
                "tool_calls": [
                    {
                        "id": tc.id,
                        "type": "function",
                        "function": {
                            "name": tc.function.name,
                            "arguments": tc.function.arguments
                        }
                    }
                    for tc in assistant_message.tool_calls
                ]
            })
            
            for tool_call in assistant_message.tool_calls:
                tool_name = tool_call.function.name
                tool_args = json.loads(tool_call.function.arguments)
                
                print(f"Calling: {tool_name}")
                print(f"Arguments: {json.dumps(tool_args, indent=2)}")
                
                function_result = klavis_client.mcp_server.call_tools(
                    server_url=mcp_server_url,
                    tool_name=tool_name,
                    tool_args=tool_args
                )
                                
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": str(function_result)
                })
            continue
        else:
            messages.append({"role": "assistant", "content": assistant_message.content})
            return assistant_message.content
    
    return "Max iterations reached without final response"

# Run the integration
result = openai_with_mcp_server(
    mcp_server_url=response.strata_server_url, 
    user_query="Check my latest 5 emails and summarize them in a Slack message to #general"
)

print(f"\n🤖 Final Response: {result}")

Strata Server Management

Add

Add servers to an existing Strata MCP server.

klavis_client.mcp_server.add_servers_to_strata(
    strata_id="strata_abc123",
    servers=[McpServerName.SLACK, McpServerName.NOTION]
)

Remove

Delete servers from an existing Strata MCP server.

klavis_client.mcp_server.delete_servers_from_strata(
    strata_id="strata_abc123",
    servers=["Slack"]
)

Get Strata Info

info = klavis_client.mcp_server.get_strata_instance(
    strata_id="strata_abc123"
)
print(info.connected_servers)  # List of connected servers
print(info.oauth_urls)  # OAuth URLs for authentication

Tool Formats

Klavis supports multiple tool formats for different LLM providers:

  • openai - OpenAI function calling format
  • anthropic - Anthropic Claude tool format
  • gemini - Google Gemini function declarations
  • mcp_native - Standard MCP protocol format

Environment Variables

KLAVIS_API_KEY=your_klavis_api_key

Best Practices

  1. Use Strata Servers: Aggregate ond or multiple MCP servers into one endpoint for easier management
  2. Handle OAuth Gracefully: Direct users to OAuth URLs and wait for completion
  3. Reuse Connections: Create Strata servers once per user and reuse them
  4. Secure API Keys: Use environment variables and never commit keys to version control

Support & Resources