MCP Kit - Model Context Protocol Toolkit 🌐🤖

🔬 A cutting-edge toolkit for experimenting with Large Language Models (LLMs) and the Model Context Protocol (MCP).

Overview 🌟

MCP Kit is an innovative platform designed to revolutionize AI model interactions by providing a standardized, extensible framework for communication between AI assistants and external tools/services. It enables developers to build intelligent, context-aware applications with seamless integration across various AI models and services.

and services tailored to your needs. For any questions or feedback, please open an issue or contact the maintainers.

Components

MCP Server

The MCP Server is a core component implementing the Model Context Protocol (MCP) specification. It facilitates structured communication between clients and AI/ML models by adhering to a standardized protocol.

Key Features:

• Protocol Compliance: Fully compliant with the MCP specification, ensuring interoperability.
• Event Streaming: Supports Server-Sent Events (SSE) for real-time data streaming.
• Scalability: Designed to handle concurrent requests and model interactions.

Technical Details:

• Library: Built using github.com/shaharia-lab/goai/mcp (Go package).
• Documentation: Detailed usage and API references available in the GoAI Docs.
• Resources:
  • MCP Repository
  • Go Package Documentation

---

MCP Client

The MCP Client acts as a configurable intermediary to connect applications to the MCP Server. It abstracts protocol complexities, enabling seamless integration with backend services.

Key Features:

• Protocol Adherence: Implements the MCP specification for server compatibility.
• Configurability: Supports custom configurations for connection timeouts, retries, and event handling.
• Real-Time Support: Processes SSE streams from the MCP Server and forwards parsed data.

Technical Details:

• Library: Shares the same github.com/shaharia-lab/goai/mcp library as the MCP Server.
• Documentation: See GoAI Docs for client-specific configurations.

---

API Server

The API Server provides an HTTP layer for frontend applications to interact with the MCP ecosystem. It orchestrates communication between the frontend, MCP Client, and external AI services (e.g., LLMs).

Key Responsibilities:

1. Frontend Interface: Exposes RESTful endpoints for user requests (e.g., prompts, model queries).
2. Request Routing: Forwards incoming requests to the MCP Client and relays responses back.
3. LLM Integration: Processes intermediate data from the MCP Client, invokes LLMs (e.g., for text generation), and formats final responses.

MCP Kit Frontend:

A dedicated frontend interface for interacting with the API Server, designed for testing and monitoring MCP workflows.

Technical Details:

• GitHub Repository: https://github.com/shaharia-lab/mcp-frontend

How Components Work Together

flowchart LR
    Frontend["🖥️ MCP Kit Frontend"]
    API["🌐 HTTP API"]
    Client["📡 MCP Client"]
    Server["🖥️ MCP Server"]
   LLM["🧠 LLM"]
    
    Frontend -- "A. Request" --> API
    API -- "B. Forward request" --> Client
    Client -- "C. Send request" --> Server
    Server -. "D. Return data via SSE events" .-> Client
    Client -- "E. Return data" --> API
    API -- "F. Process with LLM" --> LLM
    LLM -- "G. Return generated answer" --> API
    API -- "H. Final response" --> Frontend
    
    subgraph Backend Process 1
        API
        Client
        LLM
    end
    
    subgraph Backend Process 2
        Server
    end
    
    style Frontend fill:#f9f,stroke:#333,stroke-width:2px
    style API fill:#9cf,stroke:#333,stroke-width:2px
    style Client fill:#9cf,stroke:#333,stroke-width:2px
    style Server fill:#fc9,stroke:#333,stroke-width:2px
    style LLM fill:#cfc,stroke:#333,stroke-width:2px

Demo

<video src="https://github.com/user-attachments/assets/81804a29-e896-4f65-a929-05ac6a6aa92a" controls title="MCP Kit in action"></video>

Feel free to explore the MCP Kit Frontend project.

Getting Started 🚀

Prerequisites

• Go installed (for building from source)
• Docker installed (optional)

Installation

Create a configuration file

You can copy config.example.yaml to config.local.yaml and update the values as needed.

You can also reference the environment variables in the configuration file with the following syntax:

google:
  client_id: "${GOOGLE_CLIENT_ID}"

Here ${GOOGLE_CLIENT_ID} will be replaced with the value of the GOOGLE_CLIENT_ID environment variable.

Using Source Code

git clone git@github.com:shaharia-lab/mcp-kit.git
cd mcp-kit
make build

Running the MCP Server

./mcp server --config config.local.yaml

Running the API Server

./mcp api --config config.local.yaml

Run Components Separately Using Docker

docker pull ghcr.io/shaharia-lab/mcp-kit:$VERSION

# Run MCP server
docker run -d \
  --name mcp-server \
  -v $(pwd)/config.local.yaml:/config/config.yaml \
  -p 8080:8080 \
  -e MCP_SERVER_PORT=8080 \
  -e GITHUB_TOKEN=$GITHUB_TOKEN \
  -e AUTH_DOMAIN=$AUTH_DOMAIN \
  -e AUTH_CLIENT_ID=$AUTH_CLIENT_ID \
  -e AUTH_CLIENT_SECRET=$AUTH_CLIENT_SECRET \
  -e AUTH_CALLBACK_URL=$AUTH_CALLBACK_URL \
  -e AUTH_TOKEN_TTL=24h \
  -e AUTH_AUDIENCE=$AUTH_AUDIENCE \
  ghcr.io/shaharia-lab/mcp-kit:$VERSION server --config /config/config.yaml

# Run API server
docker run -d \
  --name mcp-client \
  -v $(pwd)/config.local.yaml:/config/config.yaml \
  --add-host=host.docker.internal:host-gateway \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -e MCP_SERVER_URL=http://host.docker.internal:8080/events \
  -e AUTH_DOMAIN=$AUTH_DOMAIN \
  -e AUTH_CLIENT_ID=$AUTH_CLIENT_ID \
  -e AUTH_CLIENT_SECRET=$AUTH_CLIENT_SECRET \
  -e AUTH_CALLBACK_URL=$AUTH_CALLBACK_URL \
  -e AUTH_TOKEN_TTL=24h \
  -e AUTH_AUDIENCE=$AUTH_AUDIENCE \
  -p 8081:8081 \
  ghcr.io/shaharia-lab/mcp-kit:$VERSION api --config /config/config.yaml
  
## Running the MCP Kit Frontend

docker run -d \
  --name mcp-frontend \
  -p 3001:80 \
  -e VITE_MCP_BACKEND_API_ENDPOINT=http://localhost:8081 \
  ghcr.io/shaharia-lab/mcp-frontend:latest

Using Docker Compose (Advanced)

If you want to run all the components together with basic observability and monitoring, you can use the provided docker-compose.yml file.

docker plugin install grafana/loki-docker-driver:latest --alias loki --grant-all-permissions

docker-compose up -d

Accessing the UI

http://localhost:3001

Interacting with the API

OpenAPI schema is available in openapi.yaml.

Contributing

We welcome contributions to the project! If you'd like to contribute, please follow these steps:

1. Fork the repository: Click the "Fork" button at the top of this repository to create your own copy.
2. Clone your fork: Clone your fork to your local machine using:

   git clone https://github.com/your-username/mcp-kit.git
   

3. Create a branch: Create a new branch for your changes:

   git checkout -b feature/your-feature-name
   

4. Make your changes: Implement your changes, ensure your code is clean and well-documented.
5. Test your changes: Make sure all existing tests pass and write new ones if needed. Run the tests using:

   make test
   

6. Submit a pull request: Push your changes to your forked repository and create a pull request to the main branch of this repository. Please include a clear description of your changes.

We recommend reading the Conventional Commits specification to properly format your commit messages.

Code of Conduct

Please note that by contributing to this project, you agree to adhere to our Code of Conduct.

Monitoring and Observability

MCP Kit comes with built-in monitoring and observability features using popular open-source tools:

• Prometheus: For metrics collection and monitoring
• Grafana: For visualization and dashboards
• Loki: For log aggregation
• Promtail: For log shipping and collection

These tools are pre-configured in the monitoring/ directory and can be easily deployed using Docker Compose.

License

This project is licensed under the MIT License. See the LICENSE file for details. Each component may have its own license, so please check the respective repositories/libraries for more information.