Mcp Agent Kit

The easiest way to create MCP servers, AI agents, and chatbots with any LLM

mcp-agent-kitis a TypeScript package that simplifies the creation of:

- 🔌MCP Servers(Model Context Protocol)
- 🤖AI Agentswith multiple LLM providers
- 🧠Intelligent Routersfor multi-LLM orchestration
- 💬Chatbotswith conversation memory
- 🌐API Helperswith retry and timeout

- Zero Config: Works out of the box with smart defaults
- Multi-Provider: OpenAI, Anthropic, Gemini, Ollama support
- Type-Safe: Full TypeScript support with autocomplete
- Production Ready: Built-in retry, timeout, and error handling
- Developer Friendly: One-line setup for complex features
- Extensible: Easy to add custom providers and middleware

import { createAgent } from "mcp-agent-kit"; const agent = createAgent({ provider: "openai" }); const response = await agent.chat("Hello!"); console.log(response.content);

import { createMCPServer } from "mcp-agent-kit"; const server = createMCPServer({ name: "my-server", tools: [ { name: "get_weather", description: "Get weather for a location", inputSchema: { type: "object", properties: { location: { type: "string" }, }, }, handler: async ({ location }) => { return Weather in ${location}: Sunny, 72°F; }, }, ], }); await server.start();

import { createChatbot, createAgent } from "mcp-agent-kit"; const bot = createChatbot({ agent: createAgent({ provider: "openai" }), system: "You are a helpful assistant", maxHistory: 10, }); await bot.chat("Hi, my name is John"); await bot.chat("What is my name?"); // Remembers context!

- AI Agents
- MCP Servers
- LLM Router
- Chatbots
- API Requests
- Configuration
- Examples

import { createAgent } from "mcp-agent-kit"; const agent = createAgent({ provider: "openai", model: "gpt-4-turbo-preview", temperature: 0.7, maxTokens: 2000, }); const response = await agent.chat("Explain TypeScript"); console.log(response.content);

const agent = createAgent({ provider: "openai", tools: [ { name: "calculate", description: "Perform calculations", parameters: { type: "object", properties: { operation: { type: "string", enum: ["add", "subtract"] }, a: { type: "number" }, b: { type: "number" }, }, required: ["operation", "a", "b"], }, handler: async ({ operation, a, b }) => { return operation === "add" ? a + b : a - b; }, }, ], }); const response = await agent.chat("What is 15 + 27?");

const agent = createAgent({ provider: "anthropic", system: "You are an expert Python developer. Always provide code examples.", });

Smart Tool Calling adds reliability and performance to tool execution with automatic retry, timeout, and caching.

const agent = createAgent({ provider: "openai", toolConfig: { forceToolUse: true, // Force model to use tools maxRetries: 3, // Retry up to 3 times on failure toolTimeout: 30000, // 30 second timeout onToolNotCalled: "retry", // Action when tool not called }, tools: [...], });

const agent = createAgent({ provider: "openai", toolConfig: { cacheResults: { enabled: true, ttl: 300000, // Cache for 5 minutes maxSize: 100, // Store up to 100 results }, }, tools: [...], });

// Execute a tool directly with retry and caching const result = await agent.executeTool("get_weather", { location: "San Francisco, CA", });

const agent = createAgent({ provider: "openai", model: "gpt-4-turbo-preview", toolConfig: { forceToolUse: true, maxRetries: 3, onToolNotCalled: "retry", toolTimeout: 30000, cacheResults: { enabled: true, ttl: 300000, maxSize: 100, }, debug: true, }, tools: [ { name: "get_weather", description: "Get current weather for a location", parameters: { type: "object", properties: { location: { type: "string" }, }, required: ["location"], }, handler: async ({ location }) => { // Your weather API logic return { location, temp: 72, condition: "Sunny" }; }, }, ], }); // Use in chat - tools are automatically called const response = await agent.chat("What's the weather in NYC?"); // Or execute directly with retry and caching const result = await agent.executeTool("get_weather", { location: "New York, NY", });

Create Model Context Protocol servers to expose tools and resources.

import { createMCPServer } from "mcp-agent-kit"; const server = createMCPServer({ name: "my-mcp-server", port: 7777, logLevel: "info", }); await server.start(); // Starts on stdio by default

const server = createMCPServer({ name: "weather-server", tools: [ { name: "get_weather", description: "Get current weather", inputSchema: { type: "object", properties: { location: { type: "string" }, units: { type: "string", enum: ["celsius", "fahrenheit"] }, }, required: ["location"], }, handler: async ({ location, units = "celsius" }) => { // Your weather API logic here return { location, temp: 22, units, condition: "Sunny" }; }, }, ], });

const server = createMCPServer({ name: "data-server", resources: [ { uri: "config://app-settings", name: "Application Settings", description: "Current app configuration", mimeType: "application/json", handler: async () => { return JSON.stringify({ version: "1.0.0", env: "production" }); }, }, ], });

const server = createMCPServer({ name: "ws-server", port: 8080, }); await server.start("websocket"); // Use WebSocket instead of stdio

Route requests to different LLMs based on intelligent rules.

import { createLLMRouter } from "mcp-agent-kit"; const router = createLLMRouter({ rules: [ { when: (input) => input.length < 200, use: { provider: "openai", model: "gpt-4-turbo-preview" }, }, { when: (input) => input.includes("code"), use: { provider: "anthropic", model: "claude-3-5-sonnet-20241022" }, }, { default: true, use: { provider: "openai", model: "gpt-4-turbo-preview" }, }, ], }); const response = await router.route("Write a function to sort an array");

const router = createLLMRouter({ rules: [...], fallback: { provider: 'openai', model: 'gpt-4-turbo-preview' }, retryAttempts: 3, logLevel: 'debug' });

const stats = router.getStats(); console.log(stats); // { totalRules: 3, totalAgents: 2, hasFallback: true } const agents = router.listAgents(); console.log(agents); // ['openai:gpt-4-turbo-preview', 'anthropic:claude-3-5-sonnet-20241022']

Create conversational AI with automatic memory management.

import { createChatbot, createAgent } from "mcp-agent-kit"; const bot = createChatbot({ agent: createAgent({ provider: "openai" }), system: "You are a helpful assistant", maxHistory: 10, }); await bot.chat("Hi, I am learning TypeScript"); await bot.chat("Can you help me with interfaces?"); await bot.chat("Thanks!");

const bot = createChatbot({ router: createLLMRouter({ rules: [...] }), maxHistory: 20 });

// Get conversation history const history = bot.getHistory(); // Get statistics const stats = bot.getStats(); console.log(stats); // { // messageCount: 6, // userMessages: 3, // assistantMessages: 3, // oldestMessage: Date, // newestMessage: Date // } // Reset conversation bot.reset(); // Update system prompt bot.setSystemPrompt("You are now a Python expert");

Simplified HTTP requests with automatic retry and timeout.

import { api } from "mcp-agent-kit"; const response = await api.get("https://api.example.com/data"); console.log(response.data);

const response = await api.post( "https://api.example.com/users", { name: "John", email: "john@example.com" }, { name: "create-user", headers: { "Content-Type": "application/json" }, } );

const response = await api.request({ name: "important-request", url: "https://api.example.com/data", method: "GET", timeout: 10000, // 10 seconds retries: 5, // 5 attempts query: { page: 1, limit: 10 }, });

await api.get(url, config); await api.post(url, body, config); await api.put(url, body, config); await api.patch(url, body, config); await api.delete(url, config);

All configuration is optional. Set these environment variables or pass them in code:

# MCP Server MCP_SERVER_NAME=my-server MCP_PORT=7777 # Logging LOG_LEVEL=info # debug | info | warn | error # LLM API Keys OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-... GEMINI_API_KEY=... OLLAMA_HOST=http://localhost:11434

# .env OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-... LOG_LEVEL=debug

The package automatically loads.envfiles usingdotenv.

Check out the/examplesdirectory for complete working examples:

- basic-agent.ts- Simple agent usage
- smart-tool-calling.ts- Smart tool calling with retry and caching
- mcp-server.ts- MCP server with tools and resources
- mcp-server-websocket.ts- MCP server with WebSocket
- llm-router.ts- Intelligent routing between LLMs
- chatbot-basic.ts- Chatbot with conversation memory
- chatbot-with-router.ts- Chatbot using router
- api-requests.ts- HTTP requests with retry

# Install dependencies npm install # Run an example npx ts-node examples/basic-agent.ts

- provider(required): LLM provider - "openai", "anthropic", "gemini", or "ollama"
- model(optional): Model name (defaults to provider's default)
- temperature(optional): Sampling temperature 0-2 (default: 0.7)
- maxTokens(optional): Maximum tokens in response (default: 2000)
- apiKey(optional): API key (reads from env if not provided)
- tools(optional): Array of tool definitions
- system(optional): System prompt
- toolConfig(optional): Smart tool calling configuration

- chat(message: string): Promise<AgentResponse>- Send a message and get response
- executeTool(name: string, params: any): Promise<any>- Execute a tool directly

{ content: string; // Response text toolCalls?: Array<{ // Tools that were called name: string; arguments: any; }>; usage?: { // Token usage promptTokens: number; completionTokens: number; totalTokens: number; }; }

createMCPServer(config: MCPServerConfig)

- name(optional): Server name (default: from env or "mcp-server")
- port(optional): Port number (default: 7777)
- logLevel(optional): Log level - "debug", "info", "warn", "error"
- tools(optional): Array of tool definitions
- resources(optional): Array of resource definitions

- start(transport?: "stdio" | "websocket"): Promise<void>- Start the server

createLLMRouter(config: LLMRouterConfig)

- rules(required): Array of routing rules
- fallback(optional): Fallback provider configuration
- retryAttempts(optional): Number of retry attempts (default: 3)
- logLevel(optional): Log level

- route(input: string): Promise<AgentResponse>- Route input to appropriate LLM
- getStats(): object- Get router statistics
- listAgents(): string[]- List all configured agents

Creates a new chatbot instance with conversation memory.

- agentorrouter(required): Agent or router instance
- system(optional): System prompt
- maxHistory(optional): Maximum messages to keep (default: 10)

- chat(message: string): Promise<AgentResponse>- Send message with context
- getHistory(): ChatMessage[]- Get conversation history
- getStats(): object- Get conversation statistics
- reset(): void- Clear conversation history
- setSystemPrompt(prompt: string): void- Update system prompt

Make HTTP request with retry and timeout.

- name(optional): Request name for logging
- url(required): Request URL
- method(optional): HTTP method (default: "GET")
- headers(optional): Request headers
- query(optional): Query parameters
- body(optional): Request body
- timeout(optional): Timeout in ms (default: 30000)
- retries(optional): Retry attempts (default: 3)

- api.get(url, config?)- GET request
- api.post(url, body, config?)- POST request
- api.put(url, body, config?)- PUT request
- api.patch(url, body, config?)- PATCH request
- api.delete(url, config?)- DELETE request

// Coming soon: Plugin system for custom providers

// Coming soon: Middleware support for request/response processing

// Coming soon: Streaming support for real-time responses

Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (git checkout -b feature/amazing-feature)
- Commit your changes (git commit -m 'Add amazing feature')
- Push to the branch (git push origin feature/amazing-feature)
- Open a Pull Request

- Built withTypeScript
- UsesMCP SDK
- Powered by OpenAI, Anthropic, Google, and Ollama

- Email:houessoudominique@gmail.com
- Issues:GitHub Issues
- Discussions:GitHub Discussions

Intelligent orchestration platform that routes tasks to the best AI model (Claude, Codex, Gemini, OpenCode) using LinUCB bandits, validates through consensus voting, and learns from outcomes. 29 MCP tools, dev pipeline, 8 memory backends.