​
Overview

The Klavis Unified MCP (Model-Context Protocol) Server provides a single, consolidated endpoint to interact with multiple MCP servers simultaneously. Instead of managing connections to each MCP server (like GitHub, Jira, or Slack) individually, you can connect to the Unified MCP Server and access all their tools through one interface. This simplifies your application’s architecture, reduces complexity, and makes it easier to build powerful AI agents that can leverage a wide range of tools from different services.

​
Prerequisites

  • You need a Klavis API key. If you don’t have one, you can create one here.

​
How It Works

The process involves two main stages:
  1. Create Individual MCP Server Instances: For each user of your application, you first create separate MCP server instances for each third-party service they need to connect to (e.g., a GitHub server and a Jira server). Each of these servers requires its own authentication via OAuth.
  2. Create a Unified MCP Server Instance: Once the individual servers are created and authenticated, you create a Unified MCP Server instance for that same user. The Unified Server automatically discovers and connects to all individual MCP servers associated with the user’s ID.
Your AI application then connects to this single Unified MCP Server endpoint to access tools from all the underlying services.

​
Implementation

Follow the steps below to set up and use the Unified MCP Server.
1

1. Create Individual MCP Server Instances

Before you can create a unified server, you must first create individual MCP server instances for a specific user. It’s crucial that you use the same user_id for all servers that you want to group under one unified server.Here’s how you can create a GitHub and a Jira MCP server instance for the same user.

​
Request

from klavis import Klavis
from klavis.types import McpServerName

klavis_client = Klavis(api_key="<YOUR_API_KEY>")

# Create a GitHub MCP server instance
github_server = klavis_client.mcp_server.create_server_instance(
    server_name=McpServerName.GITHUB,
    user_id="<YOUR_USER_ID>",
    platform_name="<YOUR_PLATFORM_NAME>",
)

# Create a Jira MCP server instance
jira_server = klavis_client.mcp_server.create_server_instance(
    server_name=McpServerName.JIRA,
    user_id="<YOUR_USER_ID>", # Same user_id
    platform_name="<YOUR_PLATFORM_NAME>",
)

print("GitHub Server:", github_server)
print("Jira Server:", jira_server)

​
Response

Each call will return a serverUrl, instanceId, and an oauthUrl.
{
  "serverUrl": "https://github-mcp-server.klavis.ai/mcp/?instance_id=<github-instance-id>",
  "instanceId": "<github-instance-id>",
  "oauthUrl": "https://api.klavis.ai/oauth/github/authorize?instance_id=<github-instance-id>"
}
You must guide your user through the oauthUrl for each server to grant access. The Unified MCP Server will only connect to authenticated individual servers. Refer to our OAuth documentation for more details.
2

2. Create a Unified MCP Server Instance

Once the individual MCP servers are created and authorized, you can create a Unified MCP Server instance. You only need to provide the user_id and platform_name that you used in the previous step.

​
Request

from klavis import Klavis

klavis_client = Klavis(api_key="<YOUR_API_KEY>")

# Create a Unified MCP server instance
unified_server = klavis_client.mcp_server.create_unified_server_instance(
    user_id="<YOUR_USER_ID>",
    platform_name="<YOUR_PLATFORM_NAME>",
)

print(unified_server)

​
Response

The response will contain the serverUrl for the Unified MCP Server.
Response
{
  "serverUrl": "https://unified-mcp-server.klavis.ai/mcp/?instance_id=<unified-instance-id>",
  "instanceId": "<unified-instance-id>"
}
The serverUrl is the single endpoint you’ll use for your AI application to connect to all of the user’s underlying MCP servers.
3

3. Use the Unified MCP Server

Connect your AI application or MCP client to the serverUrl obtained in the previous step. You can now access tools from all connected MCP servers (e.g., GitHub and Jira) through this single connection.You can discover all available tools by calling the list_tools endpoint on the Unified MCP Server. For more details, see the API reference for listing tools.
When a new individual MCP server is created and authenticated for a user, it will be automatically included in their Unified MCP Server without needing to recreate it.