Kogna MCP Bridge

You can connect your MCP client to the Kogna MCP Bridge to interact with Kogna’s multi-agent AI avatar system. This server exposes a bridge that forwards MCP requests to a remote Kogna backend and also supports running locally as an MCP endpoint. Use either a remote HTTP URL or a local stdio bridge to integrate with your MCP client, depending on your deployment needs.

How to use

Choose how you want to connect your MCP client to the bridge. You can use the remote MCP URL to send requests over HTTP, or run the bridge locally as an MCP stdio server that reads from standard input and writes to standard output. When running locally, you interact with the bridge by piping your requests to it and reading responses from it, similar to a command-line interface workflow. This flexibility allows you to test quickly or deploy in environments where network access to the remote backend is restricted.

How to install

Prerequisites you will need before installing include Python 3.8 or newer and a terminal that supports your preferred package manager. You may also choose to run the bridge via Docker if you prefer containerized deployments.

# macOS
brew install pipx

# Other systems
pip install pipx

# Add pipx to your PATH (if not already done)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Install the MCP bridge client that enables MCP interactions through the bridge.

pipx install kognamcp

Verify the installation by listing the available commands and help text.

kognamcp --help

Configuration and availability

The bridge can be used in two modes. The HTTP mode connects to a remote MCP server, while the stdio mode runs locally as an MCP endpoint that reads from stdin and writes to stdout. If you plan to connect via HTTP, you will configure your MCP client with the remote URL provided here.

Troubleshooting and notes

If you encounter command-not-found errors, ensure the installation completed successfully and that the executable is on your PATH. If the bridge cannot be found when starting your MCP client, use the full path obtained from which kognamcp and place it in your MCP client configuration.

If you experience connectivity issues, confirm you have internet access for the HTTP bridge or ensure the local stdio bridge is running in the expected environment.

Configuration examples

Add these MCP server configurations to your client to enable both remote HTTP access and local stdio bridging.

Security and best practices

When using the HTTP bridge, protect the URL and any authentication tokens as you would with any remote API. For local stdio usage, limit access to environments where you control the input and output streams to prevent unintended data exposure.

Tools and interactions

The bridge exposes several actions that you can invoke via your MCP client. You can start a conversation, list avatars, switch avatars or rooms, send messages, and retrieve histories or system information.

Available tools

start_kogna_conversation

Start a new conversation with Kogna avatars through the MCP bridge, initiating an interactive session with available avatars and their specialties.

send_kogna_message

Send a message to the current Kogna conversation, allowing you to continue an ongoing dialogue with the selected avatar.

list_kogna_avatars

List available Kogna avatars and their specialties, so you can choose the most suitable avatar for your task.

list_kogna_rooms

List available rooms and their descriptions to switch context or environment for the conversation.

switch_kogna_avatar

Switch to a different avatar within your current session to leverage varied capabilities.

switch_kogna_room

Switch to a different room to change the context of the conversation.

get_kogna_conversation_history

Retrieve the history of the current conversation for reference or review.

get_kogna_system_info

Get system information about the Kogna backend and bridge status to troubleshoot or monitor health.