Skip to main content
The Agent Server is a production-ready HTTP server that wraps the Kubiya MCP capabilities in an OpenAI-compatible API. This allows you to easily build custom frontends using the Vercel AI SDK or any other OpenAI-compatible client.

​
Overview

The Agent Server provides:
  1. OpenAI-compatible API: /v1/chat/completions endpoint for easy integration.
  2. SSE Streaming: Real-time streaming of responses and tool executions.
  3. Built-in LLM Support: Native integration with OpenAI, Anthropic, Together AI, and Groq.
  4. Kubiya Integration: Automatically connects the LLM to Kubiya’s MCP tools.

​
Installation

To use the Agent Server, install the SDK with the mcp extra: 
pip install "kubiya-sdk[mcp]"

​
Running the Server

Start the server using the CLI: 
kubiya mcp agent --provider together --port 8000

​
Configuration Options

OptionFlagDescription
Provider--provider, -pLLM provider (openai, anthropic, together, groq)
Model--model, -mSpecific model name (defaults vary by provider)
Port--port, -PServer port (default: 8000)
Host--host, -HServer host (default: 0.0.0.0)
Kubiya Key--kubiya-keyKubiya API Key (or KUBIYA_API_KEY env var)
Provider Key--api-keyLLM Provider API Key (or OPENAI_API_KEY, etc.)

​
Environment Variables

You can also configure the server using environment variables:
  • KUBIYA_API_KEY: Your Kubiya Platform API Key
  • OPENAI_API_KEY: Required if using OpenAI provider
  • ANTHROPIC_API_KEY: Required if using Anthropic provider
  • TOGETHER_API_KEY: Required if using Together AI provider
  • GROQ_API_KEY: Required if using Groq provider

​
API Endpoints

​
Chat Completions

POST /v1/chat/completions Standard OpenAI chat completion endpoint. Supports streaming. Request: 
{
  "model": "gpt-4",
  "messages": [
    {"role": "user", "content": "Create a workflow to restart pods"}
  ],
  "stream": true
}

​
Discovery

GET /discover Returns metadata about the agent server, useful for frontend auto-configuration. Response: 
{
  "provider": "openai",
  "model": "gpt-4",
  "features": ["streaming", "tools"],
  "api_version": "1.0.0"
}

​
Health Check

GET /health Returns 200 OK if the server is running.

​
Integration with Vercel AI SDK

You can easily connect a Next.js frontend to the Agent Server using the Vercel AI SDK. 
// app/api/chat/route.ts
import { OpenAIStream, StreamingTextResponse } from 'ai';
import OpenAI from 'openai';

// Point to your local Agent Server
const openai = new OpenAI({
  apiKey: 'dummy', // Key is handled by the server
  baseURL: 'http://localhost:8000/v1',
});

export async function POST(req: Request) {
  const { messages } = await req.json();

  const response = await openai.chat.completions.create({
    model: 'gpt-4',
    stream: true,
    messages,
  });

  const stream = OpenAIStream(response);
  return new StreamingTextResponse(stream);
}

​
Interactive Chat

For testing purposes, you can also run an interactive chat session directly in your terminal: 
kubiya mcp chat --provider openai
This connects to the same agent logic but runs in your terminal, allowing you to test workflows and tool execution without setting up a frontend.