mcphub/examples/CONFIGURATION_SCREENSHOT_GUIDE.md

Atlassian/Jira Configuration Screenshot Guide

This guide shows what your configuration should look like at each step.

📋 Configuration File Structure

Your mcp_settings.json should look like this:

{
  "mcpServers": {
    "jira": {
      "command": "uvx",
      "args": [
        "mcp-atlassian",
        "--jira-url=${JIRA_URL}",
        "--jira-username=${JIRA_USERNAME}",
        "--jira-token=${JIRA_TOKEN}"
      ]
    }
  },
  "users": [
    {
      "username": "admin",
      "password": "${ADMIN_PASSWORD_HASH}",
      "isAdmin": true
    }
  ]
}

Security Note: The password field must contain a bcrypt hash, not plain text.

To generate a bcrypt hash:

node -e "console.log(require('bcrypt').hashSync('your-password', 10))"

⚠️ CRITICAL SECURITY:

• Never use default credentials in production
• Always change the admin password before deploying
• Store password hashes, never plain text passwords

📁 File Structure

Your project should have these files:

mcphub/
├── mcp_settings.json          ← Your configuration file
├── .env                        ← Your environment variables (DO NOT COMMIT!)
├── data/                       ← Database directory (auto-created)
└── ...

🔐 Environment Variables (.env file)

# .env file content
JIRA_URL=https://mycompany.atlassian.net
JIRA_USERNAME=myemail@company.com
JIRA_TOKEN=ATBBxxxxxxxxxxxxxxxxxxx

🎯 Expected Dashboard View

After starting MCPHub, you should see:

1. Server List View

┌─────────────────────────────────────────────────┐
│ MCP Servers                                     │
├─────────────────────────────────────────────────┤
│                                                 │
│ ✅ jira                                         │
│    Status: Connected                            │
│    Type: stdio                                  │
│    Command: uvx mcp-atlassian                   │
│    Tools: 15 available                          │
│                                                 │
│    [View Details] [Restart] [Stop]              │
│                                                 │
└─────────────────────────────────────────────────┘

2. Server Details View

┌─────────────────────────────────────────────────┐
│ Server: jira                                    │
├─────────────────────────────────────────────────┤
│                                                 │
│ Status: ✅ Connected                            │
│ Type: stdio                                     │
│ Command: uvx                                    │
│                                                 │
│ Available Tools:                                │
│  • jira_search_issues                          │
│  • jira_get_issue                              │
│  • jira_list_projects                          │
│  • jira_get_project                            │
│  • ... and 11 more                             │
│                                                 │
│ Logs:                                           │
│  [INFO] Successfully connected to Jira         │
│  [INFO] Loaded 15 tools                        │
│                                                 │
└─────────────────────────────────────────────────┘

3. Connection Endpoints

Once connected, your Jira server is available at:

Endpoint	URL	Description
All Servers	http://localhost:3000/mcp	Access all configured MCP servers
Jira Only	http://localhost:3000/mcp/jira	Direct access to Jira server
SSE (Legacy)	http://localhost:3000/sse/jira	SSE endpoint for Jira

✅ Success Indicators

You'll know the configuration is working when you see:

1. ✅ Green status indicator next to the server name
2. "Connected" status in the server details
3. Tool count showing (e.g., "15 tools available")
4. No error messages in the logs
5. Server responds to health check requests

❌ Common Error Indicators

Connection Failed

┌─────────────────────────────────────────────────┐
│ ❌ jira                                          │
│    Status: Disconnected                         │
│    Error: Failed to start server                │
│    Last error: 401 Unauthorized                 │
│                                                 │
│    Possible causes:                             │
│    • Invalid API token                          │
│    • Wrong username/email                       │
│    • Incorrect Jira URL                         │
└─────────────────────────────────────────────────┘

UVX Not Found

┌─────────────────────────────────────────────────┐
│ ❌ jira                                          │
│    Status: Error                                │
│    Error: Command not found: uvx                │
│                                                 │
│    Solution: Install UV                         │
│    curl -LsSf https://astral.sh/uv/install.sh | sh │
└─────────────────────────────────────────────────┘

Environment Variable Not Set

┌─────────────────────────────────────────────────┐
│ ⚠️  jira                                         │
│    Status: Configuration Error                  │
│    Error: Environment variable JIRA_TOKEN not found │
│                                                 │
│    Solution: Check your .env file               │
└─────────────────────────────────────────────────┘

🧪 Testing Your Configuration

Test 1: Health Check

curl http://localhost:3000/api/health

Expected response:

{
  "status": "ok",
  "servers": {
    "jira": "connected"
  }
}

Test 2: List Servers

curl http://localhost:3000/api/servers

Expected response:

{
  "servers": [
    {
      "name": "jira",
      "status": "connected",
      "type": "stdio",
      "toolCount": 15
    }
  ]
}

Test 3: MCP Endpoint

curl http://localhost:3000/mcp/jira \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/list",
    "params": {}
  }'

Expected response: List of available Jira tools

📊 Log Messages Explained

Successful Startup

[INFO] Loading configuration from mcp_settings.json
[INFO] Found 1 MCP server(s) to initialize
[INFO] Starting server: jira
[INFO] Executing: uvx mcp-atlassian --jira-url=https://...
[INFO] Successfully connected client for server: jira
[INFO] Successfully listed 15 tools for server: jira
[INFO] ✅ Server jira is ready

Connection Issues

[ERROR] Failed to start server: jira
[ERROR] Error: spawn uvx ENOENT
[WARN] Server jira will retry in 5 seconds

Authentication Issues

[ERROR] Failed to connect to Jira
[ERROR] HTTP 401: Unauthorized
[ERROR] Please check your API token and credentials

🔍 Debugging Steps

If your server shows as disconnected:

1. Check logs in the dashboard or console
2. Verify environment variables are set correctly
3. Test manually with uvx:

   uvx mcp-atlassian --jira-url=https://your-company.atlassian.net --jira-username=your@email.com --jira-token=your_token
   

4. Check network connectivity to Jira
5. Verify API token is still valid
6. Restart MCPHub after making changes

📚 Additional Resources

• Quick Start Guide
• Complete Setup Guide
• MCPHub Documentation
• Atlassian API Tokens