How do I use Leantime MCP Bridge?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Leantime MCP Bridge Show me all tasks assigned to me in the Website Redesign project" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Leantime MCP Bridge

A robust Model Context Protocol (MCP) proxy bridge for Leantime project management system. Built with TypeScript and the official MCP SDK, this tool provides a reliable bridge between MCP clients and Leantime servers.

✨ Features

Built with Official MCP SDK: Uses @modelcontextprotocol/sdk for robust protocol handling
Multiple Authentication Methods: Bearer, API Key, Token, and X-API-Key headers
Protocol Version Support: MCP 2025-03-26 (latest) with backward compatibility
Advanced Transport Support: HTTP/HTTPS, Server-Sent Events (SSE), and streaming responses
TypeScript Implementation: Type-safe, maintainable codebase

Pre-Requisites

If you are self hosted, you need the MCPServer Plugin https://marketplace.leantime.io/product/mcp-server/
Personal access token (or api-key) generated through the Leantime UI

🚀 Installation

From npm

npm install -g leantime-mcp

From source

git clone https://github.com/leantime/leantime-mcp.git cd leantime-mcp npm install npm run build npm install -g .

📖 Usage

🖥️ Claude Desktop Configuration

Add to your claude_desktop_config.json:

Basic Configuration

{ "mcpServers": { "leantime": { "command": "leantime-mcp", "args": [ "https://yourworkspace.leantime.io/mcp", "--token", "YOUR_TOKEN_HERE" ] } } }

For Local Development with Self-Signed Certificates

{ "mcpServers": { "leantime": { "command": "leantime-mcp", "args": [ "https://yourworkspace.leantime.io/mcp", "--token", "YOUR_TOKEN_HERE", "--insecure" ] } } }

Using Absolute Path

{ "mcpServers": { "leantime": { "command": "node", "args": [ "/path/to/leantime-mcp/dist/index.js", "https://your-leantime.com/mcp", "--token", "YOUR_TOKEN_HERE" ] } } }

Production Configuration with Enhanced Security

{ "mcpServers": { "leantime": { "command": "leantime-mcp", "args": [ "https://yourworkspace.leantime.io/mcp", "--token", "YOUR_TOKEN_HERE", "--auth-method", "Bearer", "--max-retries", "5", "--retry-delay", "2000" ] } } }

💻 Claude Code Configuration

For Claude Code, add to your claude_config.json or use the command line:

Configuration File

{ "mcp": { "servers": { "leantime": { "command": "leantime-mcp", "args": [ "https://yourworkspace.leantime.io/mcp", "--token", "YOUR_TOKEN_HERE" ] } } } }

Command Line Usage

claude --mcp-server leantime="leantime-mcp https://your-leantime.com/mcp --token YOUR_TOKEN_HERE"

🎯 Cursor Configuration

For Cursor IDE, add to your workspace settings or global settings:

Workspace Settings (`.vscode/settings.json`)

{ "mcp.servers": { "leantime": { "command": "leantime-mcp", "args": [ "https://yourworkspace.leantime.io/mcp", "--token", "YOUR_TOKEN_HERE" ] } } }

Global Settings

Open Cursor Settings → Extensions → MCP and add:

{ "leantime": { "command": "leantime-mcp", "args": [ "https://yourworkspace.leantime.io/mcp", "--token", "YOUR_TOKEN_HERE" ] } }

🤖 OpenAI/ChatGPT Custom GPT Configuration

For ChatGPT with MCP support or OpenAI API integration:

OpenAI API Configuration

# Python example using OpenAI with MCP import openai from mcp_client import MCPClient # Initialize MCP client mcp_client = MCPClient( command="leantime-mcp", args=[ "https://yourworkspace.leantime.io/mcp", "--token", "YOUR_TOKEN_HERE" ] ) # Use with OpenAI client = openai.OpenAI(api_key="your-openai-key") response = client.chat.completions.create( model="gpt-4", messages=[{"role": "user", "content": "Show me my Leantime projects"}], tools=mcp_client.get_tools() )

Custom GPT Actions Configuration

# For Custom GPT Actions openapi: 3.0.0 info: title: Leantime MCP Proxy version: 2.0.0 servers: - url: https://yourworkspace.leantime.io/mcp paths: /tools/list: post: summary: List available tools requestBody: content: application/json: schema: type: object properties: jsonrpc: type: string default: "2.0" method: type: string default: "tools/list" id: type: integer security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT

🌐 Universal MCP Client Configuration

For any MCP-compatible client:

Standard MCP Configuration

{ "name": "leantime", "command": "leantime-mcp", "args": [ "https://yourworkspace.leantime.io/mcp", "--token", "YOUR_TOKEN_HERE" ], "env": { "NODE_ENV": "production" } }

Docker Configuration

# docker-compose.yml version: '3.8' services: leantime-mcp: image: node:18-alpine command: npx leantime-mcp https://yourworkspace.leantime.io/mcp --token YOUR_TOKEN_HERE environment: - NODE_ENV=production volumes: - ./config:/config stdin_open: true tty: true

📱 Environment-Specific Examples

Development Environment

# Local testing with debug logging leantime-mcp https://localhost:8080/mcp \ --token "dev-token-123" \ --insecure \ --no-cache \ --max-retries 1 \ 2>debug.log

Staging Environment

# Staging with moderate reliability leantime-mcp https://staging.leantime.com/mcp \ --token "staging-token-456" \ --max-retries 3 \ --retry-delay 1000

Production Environment

# Production with high reliability leantime-mcp https://leantime.company.com/mcp \ --token "prod-token-789" \ --auth-method Bearer \ --max-retries 5 \ --retry-delay 2000

🔧 Command Line Usage

leantime-mcp <url> --token <token> [options]

Parameters

<url> - The Leantime MCP endpoint URL (required)
--token <token> - Authentication token (required)
--auth-method <method> - Authentication method (optional, default: Bearer)
--insecure - Skip SSL certificate verification (optional)
--protocol-version <version> - MCP protocol version (optional)
--max-retries <num> - Maximum retry attempts (optional, default: 3)
--retry-delay <ms> - Base retry delay in milliseconds (optional, default: 1000)
--no-cache - Disable response caching (optional)

Authentication Methods

Method	Header Format	Example
`Bearer` (default)	`Authorization: Bearer <token>`	`--auth-method Bearer`
`X-API-Key`	`X-API-Key: <token>`	`--auth-method X-API-Key`

Examples

Basic usage with Bearer token

leantime-mcp https://leantime.example.com/mcp --token abc123

Using API Key authentication

leantime-mcp https://leantime.example.com/mcp --token abc123 --auth-method x-api-key

Local development with self-signed certificates

leantime-mcp https://localhost/mcp --token abc123 --insecure

Specific protocol version

leantime-mcp https://leantime.example.com/mcp --token abc123 --protocol-version 2025-03-26

High-reliability setup with custom retry settings

leantime-mcp https://leantime.example.com/mcp --token abc123 --max-retries 5 --retry-delay 2000

Disable caching for development/testing

leantime-mcp https://leantime.example.com/mcp --token abc123 --no-cache

🔧 How It Works

Protocol Handling: Uses official MCP SDK for robust JSON-RPC message handling
Authentication: Adds appropriate authentication headers based on chosen method
Transport Layer: Supports both regular HTTP responses and Server-Sent Events (SSE)
Error Handling: Comprehensive error handling with proper JSON-RPC error responses
Session Management: Tracks MCP session IDs for stateful interactions
Retry Logic: Exponential backoff with jitter prevents thundering herd problems
Smart Caching: Caches tool/resource/prompt lists to reduce server load

🔄 Advanced Features

Retry Logic with Exponential Backoff

Automatic retries: Failed requests are automatically retried (default: 3 attempts)
Exponential backoff: Delay doubles with each retry (1s → 2s → 4s...)
Jitter: Random ±25% variation prevents thundering herd effect
Configurable: Customize max retries and base delay via CLI options

Smart Response Caching

Automatic caching: tools/list, resources/list, and prompts/list responses are cached
TTL-based expiry: Cached responses expire after 5 minutes
Memory efficient: Automatic cleanup of expired cache entries
Configurable: Use --no-cache to disable for development/testing

Production-Ready Reliability

Connection resilience: Handles network interruptions gracefully
Request tracking: Numbered requests for easy debugging
Comprehensive logging: Detailed logs to stderr (won't interfere with MCP communication)
Graceful shutdown: Clean termination on SIGINT/SIGTERM

🏗️ Architecture

v2.0 Improvements over v1.x

TypeScript Rewrite: Type-safe implementation with better maintainability
Official SDK Integration: Uses @modelcontextprotocol/sdk instead of custom implementation
Enhanced Authentication: Support for multiple authentication methods
Better Error Handling: Proper JSON-RPC error responses and logging
Protocol Negotiation: Automatic protocol version negotiation
Streaming Support: Full support for SSE and streaming responses

Protocol Support

Primary: MCP 2025-03-26 (latest specification)
Fallback: MCP 2024-11-05 (backward compatibility)
Auto-negotiation: Automatically detects and uses appropriate protocol version

🧪 Development

Prerequisites

Node.js 18.0.0 or higher
TypeScript 5.4.0 or higher
Access to a Leantime instance with MCP support

Building from Source

# Clone the repository git clone https://github.com/leantime/leantime-mcp.git cd leantime-mcp # Install dependencies npm install # Build TypeScript npm run build # Test locally echo '{"jsonrpc":"2.0","id":1,"method":"ping"}' | node dist/index.js https://your-leantime.com/mcp --token your-token

Development Mode

# Watch for changes and rebuild npm run dev

🛡️ Security Considerations

HTTPS Only: Always use HTTPS in production environments
Token Security: Store tokens securely and avoid logging them
SSL Verification: Only use --insecure flag in development
Token Rotation: Consider implementing token rotation for long-running processes
Network Security: Ensure proper network security between proxy and Leantime server

🐛 Error Handling

The proxy includes comprehensive error handling for:

Network Issues: Connection timeouts, DNS resolution failures
Authentication: Invalid tokens, expired credentials
Protocol Errors: Malformed JSON-RPC messages, protocol mismatches
Server Errors: HTTP errors, invalid responses from Leantime
Transport Issues: SSE connection problems, streaming errors

All error messages are logged to stderr to avoid interfering with MCP communication on stdout.

🛠️ Troubleshooting

Common Issues and Solutions

"Mcp-Session-Id header required for POST requests"

Fixed in v2.0: The proxy now automatically captures and includes the MCP session ID in all requests after the initial handshake.

"Invalid JSON-RPC response" errors in Claude Desktop

Fixed in v2.0: The proxy now converts PHP error responses from Leantime into proper JSON-RPC error format that Claude Desktop can understand.

Connection keeps dropping/restarting

Check your token: Ensure the Leantime API token is valid and has proper permissions
Network issues: Use --max-retries 5 for unreliable connections
SSL problems: Use --insecure for development with self-signed certificates

Proxy exits immediately without error

This is normal behavior - the proxy waits for JSON-RPC messages from Claude Desktop via stdin. If you're testing manually, send a JSON-RPC message:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | leantime-mcp https://your-leantime.com/mcp --token YOUR_TOKEN

"Command not found: leantime-mcp"

Global install: Run npm install -g . from the project directory
Use absolute path: Reference the compiled script directly in your Claude Desktop config:
"command": "node", "args": ["/absolute/path/to/leantime-mcp/dist/index.js", ...]

Debug Mode

Enable verbose logging to troubleshoot connection issues:

# The proxy logs to stderr, so you can see debug info while MCP communication continues leantime-mcp https://your-leantime.com/mcp --token YOUR_TOKEN 2>debug.log

Checking Logs

Claude Desktop logs: Check ~/Library/Logs/Claude/mcp-server-leantime.log (macOS) for detailed MCP communication logs.

Proxy logs: All proxy logs go to stderr and include:

Request/response tracking with numbered IDs
Cache hit/miss information
Retry attempts and backoff timing
Session ID management
Error details and conversions

📊 Logging

The proxy provides detailed logging for debugging:

[LeantimeMCP] Initializing Leantime MCP Proxy... [LeantimeMCP] Server: https://leantime.example.com/mcp [LeantimeMCP] Auth Method: Bearer [LeantimeMCP] SSL verification: enabled [LeantimeMCP] Protocol version: 2025-03-26 [LeantimeMCP] Ready to handle MCP requests...

📄 License

MIT License - see LICENSE file for details

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes with TypeScript
Add tests if applicable
Build and test (npm run build && npm test)
Submit a pull request

💬 Support

For issues and questions:

Create an issue on GitHub Issues
Check Leantime documentation for MCP setup
Verify your token has proper permissions in Leantime

📋 Changelog

1.6.0 (Latest)

🎉 Complete TypeScript rewrite using official MCP SDK
✨ Multiple authentication methods (Bearer, ApiKey, Token, X-API-Key)
🚀 Enhanced protocol support (MCP 2025-03-26 + backward compatibility)
🔧 Improved error handling and logging
📡 Better transport layer with SSE and streaming support
🛡️ Enhanced security and session management
📦 Smaller codebase (80% reduction) with better maintainability
🔄 Advanced retry logic with exponential backoff and jitter
💾 Smart caching for tool lists and schemas (5-minute TTL)
⚡ Production-ready connection resilience and error recovery

1.x.x (Legacy)

Basic MCP proxy functionality
HTTP/HTTPS support
Bearer token authentication only
SSL verification bypass option