Conduit MCP Server Setup Assistant

July 20, 2025 · View on GitHub

This file contains instructions for AI coding assistants to help users set up the Conduit MCP (Model Context Protocol) server, enabling AI-powered integration with Atlassian tools (Jira and Confluence).

To the AI Assistant

You are helping a user set up Conduit's MCP server so their AI coding assistant can interact with Atlassian tools. This is NOT about Conduit's command-line interface - it's specifically about getting the MCP server working with their AI assistant.

Important Security Note

NEVER ask for or handle API tokens. The user will add their API token manually after you've completed the initial setup.

Setup Goals

Install Conduit package
Configure Atlassian site information (URL and email only)
Set up MCP server in their AI coding assistant
Verify everything works through the AI assistant (not command line)

Important Notes

All testing and verification will be done through the AI assistant after MCP setup
Conduit has a Streamlit-based admin UI that has known limitations on Windows, but this doesn't affect MCP functionality
Users should install Conduit using uv tool (recommended) or uvx for isolated environments
You will help with everything EXCEPT the API token

Prerequisites Check

First, determine the user's environment and available tools:

Operating System Detection:

# Check OS type
if [[ "$OSTYPE" == "linux-gnu"* ]]; then
    echo "Linux detected"
elif [[ "$OSTYPE" == "darwin"* ]]; then
    echo "macOS detected"
elif [[ "$OSTYPE" == "cygwin" ]] || [[ "$OSTYPE" == "msys" ]] || [[ "$OSTYPE" == "win32" ]]; then
    echo "Windows detected"
fi

# Alternative for cross-platform
python -c "import platform; print(f'OS: {platform.system()}')"

Python Version Check:
```
python --version || python3 --version
```
- Conduit requires Python 3.10 or higher (supports up to 3.12)

Package Manager Detection:

# Check for uv
uv --version 2>/dev/null && echo "uv is installed"

Installation Method:
- We'll use uv tool for isolated installation (recommended)
- This prevents dependency conflicts and ensures clean environment
- If uv is not installed, we'll install it first

Installation Steps

Step 1: Install uv (if needed)

First, check if uv is installed. If not, install it:

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Step 2: Install Conduit as an Isolated Tool

# Install Conduit as an isolated tool (recommended)
uv tool install conduit-connect

This creates an isolated environment preventing any dependency conflicts.

Alternative: Using uvx (Quick Execution)

For one-time or testing use:

# Run conduit commands directly without permanent installation
uvx conduit-connect --init

⚠️ Note: uvx may have conflicts with other Python tools. If you encounter issues, use the uv tool install method above.

Step 3: Verify Installation and Get MCP Server Path

# Find the uv tool directory
uv tool dir
# The binaries will be in: <uv-tool-dir>/conduit-connect/bin/

# Or use which/where to get the exact path
which mcp-server-conduit  # macOS/Linux
where mcp-server-conduit  # Windows

Expected paths:

macOS/Linux: ~/.local/share/uv/tools/conduit-connect/bin/mcp-server-conduit
Windows: %LOCALAPPDATA%\uv\tools\conduit-connect\Scripts\mcp-server-conduit.exe

Save the full path - this is critical for MCP configuration.

Step 4: Initialize Configuration

conduit --init

This creates a configuration file at:

Linux/macOS: ~/.config/conduit/config.yaml
Windows: %APPDATA%\conduit\config.yaml

Step 5: Configure Atlassian Site Information

Now we need to gather information about the user's Atlassian site:

Ask for Atlassian URL: "What is your Atlassian site URL? (e.g., https://mycompany.atlassian.net)"
Ask for Email: "What email address do you use to log into Atlassian?"
Ask for Site Alias (optional): "What would you like to call this site configuration? (default: 'default')" Explain: "This is just a nickname for your configuration, useful if you have multiple Atlassian sites"

Update the Configuration File:

Once you have this information, update their config.yaml file:

jira:
  default-site-alias: mycompany  # Use their chosen alias
  sites:
    mycompany:  # Use the same alias here
      url: "https://their-domain.atlassian.net"  # Their actual URL
      email: "their-email@company.com"  # Their actual email
      api_token: ""  # Leave empty - user will add later

confluence:
  default-site-alias: mycompany  # Usually same as Jira
  sites:
    mycompany:  # Use the same alias here
      url: "https://their-domain.atlassian.net"  # Usually same as Jira URL
      email: "their-email@company.com"  # Their actual email
      api_token: ""  # Leave empty - user will add later

content_dir: ~/.config/conduit/content  # Leave as default

Multi-Site Configuration (if needed):

If the user mentions having multiple Atlassian sites, help them add more:

jira:
  default-site-alias: production
  sites:
    production:
      url: "https://prod.atlassian.net"
      email: "user@company.com"
      api_token: ""  # User will add later
    staging:
      url: "https://staging.atlassian.net"
      email: "user@company.com"
      api_token: ""  # User will add later

Step 6: API Token Instructions

After updating the configuration file, provide these instructions to the user:

IMPORTANT - Manual Step Required

"I've updated your configuration file with your Atlassian site information. Now you need to add your API token manually:

Go to: https://id.atlassian.com/manage-profile/security/api-tokens
Click 'Create API token'
Give it a descriptive name (e.g., 'Conduit Integration')
Copy the token immediately (it won't be shown again)
Open your config file at: [show the path based on their OS]
Find the api_token: "" lines and paste your token between the quotes
Save the file

Once you've added your API token, we can proceed with testing the connection."

which mcp-server-conduit  # Save this path

Windows Note: Inform the user:

"Note: The Conduit admin UI has known limitations on Windows, but this doesn't affect the core MCP functionality you'll be using."

Use the claude mcp add-json command to add Conduit:

# The exact path will vary based on OS when using uv tool
# Common paths:
# macOS/Linux: ~/.local/share/uv/tools/conduit-connect/bin/mcp-server-conduit
# Windows: C:\Users\[username]\AppData\Local\uv\tools\conduit-connect\Scripts\mcp-server-conduit.exe

claude mcp add-json -s user Conduit '{"type":"stdio","command":"[YOUR_PATH_HERE]"}'

Replace [YOUR_PATH_HERE] with the actual path from Step 3.

For Claude Desktop:

Get the MCP server path (from Step 3)

Direct user to configure Claude:

Open Claude Desktop
Go to: Claude menu > Settings > Developer > Edit Config
Add Conduit to the configuration:

macOS/Linux:

{
  "mcpServers": {
    "conduit": {
      "command": "/Users/[username]/.local/share/uv/tools/conduit-connect/bin/mcp-server-conduit"
    }
  }
}

Windows:

{
  "mcpServers": {
    "conduit": {
      "command": "C:\\Users\\[username]\\AppData\\Local\\uv\\tools\\conduit-connect\\Scripts\\mcp-server-conduit.exe"
    }
  }
}

For Cursor:

Get the MCP server path (from Step 3)
Direct user to configure Cursor using the GUI:
- Open Cursor Settings (Cmd/Ctrl + ,)
- Navigate to: Cursor Settings > Features > MCP Tools
- You'll see the list of enabled MCP servers
- Click the "+ New MCP Server" button at the bottom
- This opens the configuration file

Add Conduit to the configuration:

macOS/Linux:

{
  "Conduit": {
    "command": "/Users/[username]/.local/share/uv/tools/conduit-connect/bin/mcp-server-conduit"
  }
}

Windows:

{
  "Conduit": {
    "command": "C:\\Users\\[username]\\AppData\\Local\\uv\\tools\\conduit-connect\\Scripts\\mcp-server-conduit.exe"
  }
}

Note: The server name MUST be "Conduit" with a capital C for proper recognition.

The configuration file location is:
- macOS/Linux: ~/.cursor/mcp.json
- Windows: %USERPROFILE%\.cursor\mcp.json

For Windsurf:

Get the MCP server path (from Step 3)
Direct user to configure Windsurf:
- Click the "Manage plugins" button in the bottom panel
- In the plugins list, find "Conduit" (it will show "15 / 15" tools)
- Click the "Configure" button next to code-understanding or any other server
- This opens the mcp_config.json file

Add Conduit to the mcpServers section:

macOS/Linux:

{
  "mcpServers": {
    "Conduit": {
      "command": "/Users/[username]/.local/share/uv/tools/conduit-connect/bin/mcp-server-conduit"
    }
  }
}

Windows:

{
  "mcpServers": {
    "Conduit": {
      "command": "C:\\Users\\[username]\\AppData\\Local\\uv\\tools\\conduit-connect\\Scripts\\mcp-server-conduit.exe"
    }
  }
}

Note: The server name MUST be "Conduit" with a capital C.

The configuration file location is:
- macOS/Linux: ~/.codeium/windsurf/mcp_config.json
- Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
After saving, you can verify in the Manage plugins panel that Conduit shows "15 tools"

For Other AI Assistants:

If using a different MCP-compatible assistant, the general pattern is:

Server type: stdio
Command: Full path to mcp-server-conduit
No additional arguments needed

Step 8: Verify MCP Integration

The easiest way to verify everything is working:

Start a new session in the AI coding assistant (Claude Code, Claude Desktop, Cursor, Windsurf, etc.)
- This ensures the MCP tools are properly loaded
- For Windsurf: You can also click "Refresh" in the Manage plugins panel
Visual verification (Windsurf only):
- Open the Manage plugins panel
- Look for "Conduit 15 / 15" in the list
- This confirms all 15 Conduit tools are loaded
Simple verification test: Tell the AI assistant: "List all my Atlassian site aliases"

If everything is configured correctly, the AI assistant should:
- Use the Conduit MCP tool
- Show your configured site aliases (e.g., "default", "mycompany", etc.)
If the test fails:
- Ensure you started a NEW session after adding the MCP server
- Verify the API token was added to config.yaml
- Check that the MCP server path is correct
- See the Troubleshooting section below for detailed help

Troubleshooting

Help the user troubleshoot any issues they encounter:

Installation Issues

"Command not found" for mcp-server-conduit:
- Check uv tool directory: uv tool dir
- Try finding the executable manually:
  - macOS/Linux: find ~/.local/share/uv -name mcp-server-conduit 2>/dev/null
  - Windows: Search in %LOCALAPPDATA%\uv\tools
- Verify installation: uv tool list | grep conduit-connect
Installation fails:
- Check Python version (must be 3.10+)
- Force reinstall: uv tool install --force conduit-connect
- Clear uv cache if needed: uv cache clean
- On Windows, may need to run as administrator
- For dependency conflicts with uvx: uvx cache clean

MCP Configuration Issues

"List all my Atlassian site aliases" doesn't work:
- Most common: Forgot to start a NEW session after adding MCP
- Verify the MCP server path is correct
- Check for JSON syntax errors in MCP config
- Try removing and re-adding the MCP server
- Ensure API token was added to config.yaml
MCP server not found by AI assistant:
- Double-check the path from which/where command
- On Windows, ensure path uses forward slashes or escaped backslashes
- Try using the full absolute path
- Verify file exists at that path
"No Conduit tools available" in AI assistant:
- Restart the AI assistant completely
- Check MCP server name is exactly "Conduit" (capital C) in the configuration
- For Cursor: Verify in ~/.cursor/mcp.json that the key is "Conduit" not "conduit"
- For Windsurf: Check ~/.codeium/windsurf/mcp_config.json and verify "Conduit" is capitalized
- In Windsurf: Check Manage plugins panel - Conduit should show "15 tools"
- Verify the command path points to mcp-server-conduit (not conduit)

Configuration Issues

API token errors:
- Ensure no extra spaces before/after token
- Token should be in quotes in yaml file
- Verify token hasn't expired
- Try generating a new token
Site not found errors:
- Check site alias matches in config
- Ensure URL includes https://
- Verify email matches Atlassian account

Platform-Specific Issues

Windows-specific:
- Use where instead of which for paths
- Paths in JSON may need double backslashes: C:\\\\Users\\\\...
- Or use forward slashes: C:/Users/...
- Admin UI has known limitations - this is normal
macOS-specific:
- With uv tool, paths will be in ~/.local/share/uv/tools/
- Check uv tool dir for exact location
Linux-specific:
- Ensure ~/.local/bin is in PATH
- May need to logout/login for PATH changes

Verification Steps

If issues persist, help the user verify each component:

Config file exists:
- Linux/macOS: ls ~/.config/conduit/config.yaml
- Windows: dir %APPDATA%\conduit\config.yaml
Config has API token:
- Check that api_token: has a value (not empty quotes)
MCP server executable exists:
- Check the path they're using actually has the file
Try verbose mode in AI assistant:
- Some AI assistants show MCP errors in developer/debug mode

Next Steps

Once the "list all my Atlassian site aliases" command works in the AI assistant:

The user can explore MCP capabilities:
- Search Jira issues: "Search for my open Jira tickets"
- Get Confluence pages: "Show me pages in the DOCS space"
- Create issues: "Create a new Jira issue in project ABC"
- Create Confluence pages: "Create a new Confluence page with markdown"
Point them to resources:
- Conduit documentation: https://github.com/codingthefuturewithai/conduit
- Report issues: GitHub issues page
- MCP protocol info: https://modelcontextprotocol.io

Important Security Reminders

NEVER ask for or handle API tokens
ALWAYS have users add API tokens manually after you complete setup
CLEARLY indicate when they need to add their token
REMIND users to keep their config.yaml file secure

Summary Checklist

Before considering setup complete, verify:

Quick Test After Setup

The simplest verification after everything is configured:

Start a NEW session in the AI coding assistant
Say: "List all my Atlassian site aliases"
If it works, setup is complete!

Remember: Be patient and helpful. Setup can be complex, but once complete, Conduit provides powerful integration between AI assistants and Atlassian tools.

Conduit MCP Server Setup Assistant

To the AI Assistant

Important Security Note

Setup Goals

Important Notes

Prerequisites Check

Installation Steps

Step 1: Install uv (if needed)

Step 2: Install Conduit as an Isolated Tool

Alternative: Using uvx (Quick Execution)

Step 3: Verify Installation and Get MCP Server Path

Step 4: Initialize Configuration

Step 5: Configure Atlassian Site Information

Step 6: API Token Instructions

Step 7: Prepare for MCP Configuration

Step 8: Configure AI Assistant MCP Integration

For Claude Code (Recommended Method):

For Claude Desktop:

For Cursor:

For Windsurf:

For Other AI Assistants:

Step 8: Verify MCP Integration

Troubleshooting

Installation Issues

MCP Configuration Issues

Configuration Issues

Platform-Specific Issues

Verification Steps

Next Steps

Important Security Reminders

Summary Checklist

Quick Test After Setup