🚀 Kodus MCP Manager

🔌 Multi-Cloud Platform Manager - A robust system for managing MCP integrations with providers like Composio.

---

📋 Table of Contents

• 🏗️ Prerequisites
• 🔌 Providers
• ⚙️ Configuration
• 🚀 Installation
• 🔥 Running the Application
• 🚀 Self-Hosted
• 🆕 Adding a New Provider
• 🧪 Testing
• 📫 Postman
• 📚 OpenAPI / Swagger
• 🐛 Troubleshooting

---

🏗️ Prerequisites

Tool	Minimum Version	Status	Description
📟 Node.js	v22.22.0	✅ Required	JavaScript runtime
🐳 Docker	Latest	✅ Required	For PostgreSQL
🐳 Docker Compose	Latest	✅ Required	Container orchestration
🔑 Composio API Key	-	✅ Required	For Composio integration

---

🔌 Providers

📊 Available Providers

Provider	Status	Description	Documentation
🎯 Composio	✅ Active	Automation and integration platform	Docs
🏢 Kodus	✅ Active	Kodus-managed MCPs (Kodus MCP, Context7 MCP & Kodus Docs MCP)	-
➕ New Provider	🔄 In Development	Add your own provider	Guide

🔧 Composio Setup

To use the Composio provider, you need to:

1. 🔑 Create an integration for any app on the Composio platform
2. 🖥️ Set up an MCP Server for this integration
3. 📋 Configure the required environment variables

---

⚙️ Configuration

🌍 Environment Variables

In the .env.test file at the project root:

# 🚀 Application
NODE_ENV=development
PORT=3000

# 🔐 JWT
JWT_SECRET=your-super-secret-jwt-key

# 🔌 Providers
MCP_PROVIDERS=composio

# 🎯 Composio
COMPOSIO_API_KEY=your-composio-api-key
COMPOSIO_BASE_URL=https://backend.composio.dev

# 🗄️ Database
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=kodus
DB_PASSWORD=kodus123
DB_DATABASE=kodus_mcp

# 🔗 URLs
# Used as redirect after OAuth2 login
REDIRECT_URI=http://localhost:3000/callback

---

🗄️ Database Structure

📊 Schema: mcp-manager

The project uses a dedicated schema to organize all application tables:

-- Main schema
CREATE SCHEMA IF NOT EXISTS "mcp-manager";

📋 Tables

🔗 mcp_connections

Main table for storing MCP connections:

Column	Type	Description
id	UUID	Primary key (uuid_generate_v4)
organizationId	VARCHAR	Organization ID
integrationId	VARCHAR	Integration ID
provider	VARCHAR	Provider name (e.g., composio)
status	VARCHAR	Connection status
appName	VARCHAR	Application name
mcpUrl	VARCHAR	MCP server URL
allowedTools	JSONB	List of allowed tools
metadata	JSONB	Additional connection data
createdAt	TIMESTAMP	Creation date
updatedAt	TIMESTAMP	Last update date
deletedAt	TIMESTAMP	Deletion date (soft delete)

📝 migrations

TypeORM migration control table:

Column	Type	Description
id	SERIAL	Primary key
timestamp	BIGINT	Migration timestamp
name	VARCHAR	Migration name

🔧 Useful Commands

# Check database structure
docker-compose exec kodus-mcp-manager psql -h db_postgres -U $API_PG_DB_USERNAME -d $API_PG_DB_DATABASE -c "\dt mcp-manager.*"

# Check connection data
docker-compose exec kodus-mcp-manager psql -h db_postgres -U $API_PG_DB_USERNAME -d $API_PG_DB_DATABASE -c "SELECT * FROM \"mcp-manager\".mcp_connections;"

# Check executed migrations
docker-compose exec kodus-mcp-manager psql -h db_postgres -U $API_PG_DB_USERNAME -d $API_PG_DB_DATABASE -c "SELECT * FROM \"mcp-manager\".migrations;"

---

🚀 Installation

📥 1. Clone the Repository

git clone https://github.com/kodustech/kodus-mcp-manager.git
cd kodus-mcp-manager

📦 2. Install Dependencies

yarn install

---

🔥 Running the Application

🛠️ Local Development

📋 Prerequisites

# 🐳 Start PostgreSQL database
docker-compose up -d

# 📊 Check if database is running
docker-compose ps

🗄️ Database Setup

# 🔄 Run migrations (creates schema and tables automatically)
yarn migrate

# Or run steps separately:
# 1. Create schema (if needed)
yarn pre:migrate

# 2. Run migrations
yarn migration:run

🚀 Start Application

# 🚀 Start in development mode
yarn start:dev

# Or use Docker
docker-compose exec kodus-mcp-manager yarn start:dev

The application will be available at: http://localhost:3101

🏭 Production

# 🏗️ Build the application
yarn build

# 🚀 Run in production
yarn start:prod

🐳 Docker (Alternative)

# 🚀 Start everything with Docker
docker-compose up -d

# 📊 Check status
docker-compose ps

# 🔄 Run migrations in container
docker-compose exec kodus-mcp-manager yarn migrate

📋 Available Scripts

Command	Description
yarn migrate	Run complete migrations (schema + tables)
yarn pre:migrate	Create schema if it doesn't exist
yarn migration:run	Run TypeORM migrations
yarn migration:generate	Generate new migration
yarn start:dev	Start application in development mode
yarn docker:up	Start Docker containers
yarn docker:down	Stop Docker containers

---

🚀 Self-Hosted

We provide a complete self-hosted deployment kit using Docker.

⏱️ TL;DR Summary

• 📋 Requirements: Docker + Existing Postgres (or use the provided compose service).
• ⚡ Steps:
  1. Copy .env.example to .env and configure it.
  2. Important: Set NODE_ENV to control the environment (e.g., production, development).
  3. Run docker compose up -d.

Check the Self-Hosted Guide for detailed instructions.

---

🆕 Adding a New Provider

📋 Step by Step

1️⃣ Configure Provider

# Add to .env file
MCP_PROVIDERS=composio,new_provider

2️⃣ Create Provider Class

// src/modules/providers/new_provider/new_provider.provider.ts

import { BaseProvider } from '../base.provider';

export class NewProviderProvider extends BaseProvider {
    // 🔧 Provider implementation

    async getIntegrations() {
        // Your logic here
    }

    async initiateConnection() {
        // Your logic here
    }

    // ... other required methods
}

3️⃣ Create Client (If Needed)

// src/clients/new_provider/index.ts

export class NewProviderClient {
    constructor(private config: any) {}

    async makeApiCall() {
        // External API calls
    }
}

4️⃣ Create Tests

// test/provider/new_provider.spec.ts

describe('NewProviderProvider', () => {
    // Your tests here
});

---

🧪 Testing

# 🧪 Run all tests
yarn test

📖 View complete testing documentation

---

📫 Postman

📥 Import Collection

1. Open Postman
2. Import → File
3. Select: postman/kodus-mcp-manager.postman_collection.json

🔧 Configure Variables

Variable	Value	Description
baseUrl	http://localhost:3000	API base URL
provider	composio	Default provider
token	your-jwt-token	Authentication token

🎯 Available Endpoints

• 🔗 Connections: List, search, update
• 🔌 Integrations: List, details, parameters, tools, create
• 🛠️ Tool Selection: Get available tools, get selected tools, update selected tools
• 🚀 Connect: Initiate connection with provider

🛠️ Tool Selection

The system now supports dynamic tool selection and management:

Available Tools

GET /mcp/{provider}/integrations/{integrationId}/available-tools

Returns all available tools for a specific integration.

Selected Tools

GET /mcp/{provider}/integrations/{integrationId}/selected-tools

Returns currently selected tools for an integration.

Update Selected Tools

PUT /mcp/{provider}/integrations/{integrationId}/selected-tools
Content-Type: application/json

{
  "allowedTools": ["KODUS_LIST_REPOSITORIES", "KODUS_GET_KODY_RULES"]
}

Updates the selected tools for an integration.

🔌 Integration Management

The system supports creating integrations directly in the database:

Create Integration

POST /mcp/integration/{provider}
Authorization: Bearer {token}
Content-Type: application/json

{
  "integrationId": "kd_mcp_oTUrzqsaxTg",
  "mcpUrl": "https://mcp.kodus.io"
}

Creates an integration for the organization with the specified provider. The integrationId is passed in the request body. If the integration already exists, returns the existing one. Allows custom configuration of MCP URL.

Example:

POST /mcp/integration/kodusmcp

---

📚 OpenAPI / Swagger

Swagger UI and OpenAPI JSON are exposed when API_DOCS_ENABLED=true.

🔐 Basic Auth (required)

Set the following environment variables:

API_DOCS_ENABLED=true
API_DOCS_PATH=/docs
API_DOCS_SPEC_PATH=/openapi.json
API_DOCS_BASIC_USER=dev
API_DOCS_BASIC_PASS=devpass
API_DOCS_SERVER_URLS=
API_DOCS_BASE_URL=

📄 Endpoints

• Swagger UI: /docs
• OpenAPI JSON: /openapi.json

📦 Export OpenAPI

OPENAPI_SOURCE_URL=http://localhost:3101/openapi.json \
OPENAPI_BASIC_AUTH=dev:devpass \
yarn openapi:export

✅ Lint OpenAPI

yarn openapi:lint

---

🐛 Troubleshooting

❌ Common Issues

🔴 "Port 3101 already in use"

# Find process on port 3101
lsof -i :3101

# Kill process
kill -9 <PID>

# Or use different port
PORT=3102 yarn start:dev

🔴 "Database connection failed"

# Check if PostgreSQL is running
docker-compose ps

# Restart database
docker-compose restart db_postgres

# Check logs
docker-compose logs db_postgres

🔴 "Migration failed - schema does not exist"

# Create schema manually
yarn pre:migrate

# Or run complete migrations
yarn migrate

🔴 "Migration failed - table already exists"

# Check executed migrations
docker-compose exec kodus-mcp-manager npm run typeorm -- migration:show

# Revert last migration if needed
yarn migration:revert

# Or reset database completely
docker-compose down -v
docker-compose up -d
yarn migrate

🔴 "Composio API Key invalid"

# Check environment variable
echo $COMPOSIO_API_KEY

# Test API key
curl -H "x-api-key: $COMPOSIO_API_KEY" https://backend.composio.dev/api/v1/auth_configs

🔴 "Script create-schema.sh failed"

# Check if database container is running
docker ps | grep db_postgres

# Check environment variables
cat .env | grep API_PG_DB

# Run script manually
./scripts/create-schema.sh

---

📚 Useful Resources

Resource	Link	Description
📖 NestJS Documentation	nestjs.com	Base framework
🎯 Composio Docs	docs.composio.dev	Main provider
🐳 Docker Docs	docs.docker.com	Containerization
📫 Postman	postman.com	API testing

---

🤝 Contributing

1. Fork the project
2. Create a feature branch (git checkout -b feature/new-feature)
3. Commit your changes (git commit -m 'Add new feature')
4. Push to the branch (git push origin feature/new-feature)
5. Open a Pull Request

---

📄 License

This project is under the MIT license. See the LICENSE file for more details.

---

🎉 Kodus MCP Manager Project

[](yarn start:prod) [](yarn test)

Made with ❤️ by the Kodus team