Radius MCP Server

The Radius MCP Server is a comprehensive Model Context Protocol (MCP) server that provides authentication, calendar management, and session handling capabilities for AI agents and developer tools.

This server offers a complete business productivity suite, enabling AI agents to authenticate users, manage calendar events, create meetings, and maintain persistent API sessions for seamless integration with Russian business platforms.

Project Structure

The codebase is organized as follows:

Key Components

Core Infrastructure

• src/common/: Shared utilities for HTTP requests, event handling, and versioning

• src/http-server.ts: Express server with MCP and SSE endpoints

• src/server.ts: MCP server initialization and tool registration

• src/schemas.ts: Zod schemas for data validation and TypeScript types

• src/index.ts: Application entry point with environment configuration

Business Logic Tools

• src/tools/auth-tools.ts: Complete authentication system with session management

  • Sign-in with email/password and automatic API key storage

  • Password management (check/change)

  • Session lifecycle management (login/logout/info)

  • Connection testing and debugging

• src/tools/calendar-tools.ts: Comprehensive calendar and meeting management

  • Personal and user calendar retrieval

  • Meeting creation, retrieval, and management

  • User availability checking

  • Meeting attention notifications

• src/tools/hello-world.ts: Simple demonstration tool

• src/tools/index.ts: Central tool registration hub

DevOps & Deployment

• GitLab CI/CD Pipeline: Automated testing, building, and deployment

• Docker Support: Containerized development and production deployment

• Kubernetes Helm Charts: Production-ready container orchestration

• Multi-environment Config: Separate configurations for dev/testing/production

Features

• Session Management: Persistent API key storage across requests

• Multi-API Integration: Authorization and Calendar microservice connectivity

• Error Handling: Comprehensive error reporting and debugging

• Type Safety: Full TypeScript implementation with Zod validation

• Scalable Architecture: Modular tool system for easy extension

Core Capabilities

The Radius MCP Server provides enterprise-grade functionality for AI agents:

🔐 Authentication & Session Management

• Complete Sign-in Flow: Authenticate with email/password, automatically receive and store API keys

• Session Persistence: Maintain authentication across multiple tool calls

• Password Management: Check and change user passwords securely

• Multi-session Support: Handle multiple concurrent user sessions

📅 Calendar & Meeting Management

• Personal Calendar: Retrieve your calendar events with date filtering

• User Calendar Access: View any user's calendar by ID

• Meeting Creation: Create meetings with invitations and notifications

• Availability Checking: Check user availability before scheduling

• Meeting Management: Get meeting details and attention-required meetings

🛠️ Developer Features

• Type-Safe API: Full TypeScript implementation with Zod validation

• Error Handling: Comprehensive error reporting and debugging tools

• Flexible Configuration: Environment variables and parameter overrides

• Session Debugging: Tools to inspect and manage authentication sessions

• Modular Architecture: Easy to extend with additional business tools

🚀 Production Ready

• CI/CD Pipeline: Automated testing, building, and deployment with GitLab

• Container Support: Docker and Kubernetes deployment ready

• Multi-environment: Separate configurations for development, testing, and production

• Monitoring: Built-in logging and debugging capabilities

Example: Configuring MCP Server (Local with npx & Remote with SSE)

You can connect to your Radius MCP server either by running it locally with npx or by connecting to a remote server using the SSE MCP type. Below are configuration examples for both approaches in popular clients.

VSCode MCP Server Configuration

Add this to your .vscode/settings.json or mcp.json:

Local (npx)

Remote (SSE)

• Replace <your-server-host> with your server's public IP or domain.

• Use the npx config for local development, and the sse config for connecting to a remote server.

Claude Desktop Configuration

Local (npx)

Remote (SSE)

Generic MCP Client

If your client supports specifying the MCP type and endpoint, use:

Notes

• For local development, use the npx configuration to run the server on demand.

• For remote access, use the sse configuration and ensure your server is accessible from the client (open firewall, correct port, etc.).

• For production, use HTTPS and a secure domain.

• The /sse endpoint is compatible with any MCP client that supports the SSE transport.

What can you do with it?

This server provides comprehensive business productivity capabilities that enable AI agents to:

🔐 Complete User Authentication

• Sign in with credentials: Authenticate users with email/password and automatically manage API keys

• Session management: Maintain persistent authentication across multiple operations

• Password operations: Securely check and change user passwords

• Multi-user support: Handle multiple concurrent user sessions with isolation

📅 Advanced Calendar Management

• Personal calendar access: Retrieve and filter your calendar events by date range

• Cross-user calendar viewing: Access any user's calendar for scheduling coordination

• Meeting lifecycle management: Create, retrieve, and manage meeting details

• Smart scheduling: Check user availability before creating meetings

• Notification handling: Get meetings requiring attention or responses

🛡️ Enterprise-Grade Session Handling

• Automatic API key management: Store and reuse authentication tokens seamlessly

• Session isolation: Support multiple concurrent user sessions

• Connection testing: Validate authentication status and API connectivity

• Graceful error handling: Comprehensive error reporting and recovery

🔧 Developer-Friendly Integration

• Type-safe operations: Full TypeScript implementation with Zod validation

• Flexible authentication: Support both manual API keys and automatic sign-in flows

• Environment configuration: Easily configure API endpoints and credentials

• Comprehensive logging: Detailed debugging and monitoring capabilities

This makes the server ideal for building AI assistants that need to interact with Russian business platforms, manage user authentication, and coordinate calendar activities in a secure, scalable manner.

Development

Building and Running (Local)

Development Mode

The npm run dev command provides a development server with:

• Hot reload: Automatically restarts when you change TypeScript files

• Direct TypeScript execution: No need to build first using ts-node

• File watching: Monitors src/ directory for changes

• Development environment: Sets NODE_ENV=development

Testing

Docker

The Radius MCP Server includes Docker support for easy deployment and development.

Docker Compose (Recommended)

Production

Development

Manual Docker Commands

Docker Configuration

The Docker setup includes:

• Multi-stage build for optimized production images

• Health checks for container monitoring

• Non-root user for security

• Development profile with volume mounting for hot reload

• Port 3000 exposed for the MCP server

Ports

• Production: http://localhost:3000

• Development: http://localhost:3001

Environment Variables

You can customize the Docker deployment by setting environment variables in a .env file or directly in the docker-compose.yml file.

Available Tools

Hello World Tool

• hello_world: A simple tool that greets the world

Authorization Tools

The server includes authorization functionality for password management and session control:

Authentication & Session Management

• auth_sign_in: Sign in with email and password, automatically store API key

  • Parameters: account (required), password (required), platform (optional, default: "WEB"), session_id (optional)

  • Description: Complete sign-in flow - authenticates with email/password and automatically stores received API key in session

• auth_login: Authenticate and store API key for session

  • Parameters: api_key (required), session_id (optional)

  • Description: Stores an existing API key in session for automatic authentication in subsequent requests

• auth_logout: Logout and clear session

  • Parameters: session_id (optional)

  • Description: Clears stored API key from session

• auth_session_info: Get current session information

  • Parameters: session_id (optional)

  • Description: Shows current session status and stored authentication info

• auth_test_connection: Test authenticated connection to authorization API

  • Parameters: session_id (optional)

  • Description: Tests if stored credentials are working

Password Management

• auth_check_password: Check current password

  • Parameters: password (required), api_key (optional), session_id (optional)

  • Description: Verifies your current password

• auth_change_password: Change current password

  • Parameters: password (required), new_password (required), api_key (optional), session_id (optional)

  • Description: Changes your password from current to new one

Calendar Tools

The server includes comprehensive calendar functionality for the Russian calendar microservice:

Get Calendar Events

• calendar_get_my: Get your calendar events

  • Parameters: start, end (optional dates), api_key (optional), session_id (optional)

  • Description: Retrieves your personal calendar events for specified date range

• calendar_get_by_user: Get calendar events for a specific user

  • Parameters: user_id (required), start, end (optional), api_key (optional), session_id (optional)

  • Description: Retrieves calendar events for any user by their ID

Meeting Management

• meeting_create: Create a new meeting

  • Parameters: title (required), description, place, start (required), end (required), invited (user IDs), notify, api_key (optional), session_id (optional)

  • Description: Creates a new meeting with specified details and invites users

• meeting_get: Get specific meeting details

  • Parameters: meeting_id (required), api_key (optional), session_id (optional)

  • Description: Retrieves detailed information about a specific meeting

• meeting_get_user_availability: Check user availability for meetings

  • Parameters: start (required), end (required), user_ids (required), meeting_id (optional exclude), api_key (optional), session_id (optional)

  • Description: Checks if specified users are available during the given time period

• meeting_get_requiring_attention: Get meetings requiring attention

  • Parameters: api_key (optional), session_id (optional)

  • Description: Retrieves list of meetings that need your attention or response

Authentication Configuration

Environment Variables

• AUTH_API_HOST_URL: Authorization API base URL (default: https://api.development.myradius.ru)

• AUTH_API_KEY: Default API key for authorization (can be overridden per request)

• CALENDAR_API_HOST_URL: Calendar API base URL (default: http://localhost:8000)

• CALENDAR_API_KEY: Default API key for calendar (can be overridden per request)

Session Management

The server supports persistent session management with two authentication flows:

Complete Sign-in Flow:

1. Use auth_sign_in with email/password to authenticate and automatically store API key

2. All subsequent API calls will automatically use the stored key

3. No need to manually handle API keys

Manual API Key Flow:

1. Use auth_login to store an existing API key in memory

2. All subsequent API calls will automatically use the stored key

Additional Features: 3. Override stored key by passing api_key parameter to any tool 4. Use session_id to manage multiple concurrent sessions 5. Clear session with auth_logout 6. Check session status with auth_session_info

This allows for convenient authentication flow where you authenticate once and then use tools without specifying credentials each time.

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.